Installation instructions for the ParaMonte MATLAB library | ParaMonte: Parallel Monte Carlo and Machine Learning Library

Edit this page

Note: The current pre-release of the ParaMonte MATLAB library has been tested only with the most recent versions of MATLAB (> R2023a):

Fully compatible and tested with MATLAB 2024b, 2024a, 2023b, 2023a on all supported platforms (Linux, Darwin, Windows).
Mostly compatible but untested with MATLAB 2022b, 2022a, 2021b, 2021a, 2020b, 2020a, 2019b.
Specifically, the functionalities that require MEX files (e.g., the ParaMonte samplers) may not work as the new compilers are incompatible with older MATLAB versions.
Refer to the build instructions from source code if you need to rebuild the MEX files from source code for your specific older MATLAB installation.
Partially compatible but untested with MATLAB 2019a, 2018b: The tiled visualization functionalities of pm.vis that rely on tiledlayout new functionality of MATLAB 2019 will not work.
Support for MATLAB R2018a on Windows is unstable. In particular, MATLAB R2018a Update 6 is required for the proper functioning of the ParaMonte sampler routines on Windows systems with MATLAB R2018a.
If you encounter incompatibilities or bugs in the ParaMonte library with any of the supported MATLAB versions in the above, please report the issue on the GitHub issues page of the library.
incompatible and untested with MATLAB < 2018a

We strongly recommend to either upgrade your MATLAB software to most recent versions or use the binary releases and installation guidelines for ParaMonte 1.

Tip: The term AMD64 CPU architecture is synonymous with x86-64, x86_64, x64, and Intel 64, all referring to the 64-bit processor that adds 64-bit computing capabilities to the x86 architecture. The AMD64 architecture supports more virtual and physical memory than its 32-bit counterpart, which enables programs to store more data in memory.

Tip: The term ARM64 CPU architecture is synonymous with AArch64, all referring to the 64-bit Execution state of the ARM architecture family. Examples of computers with ARM64 processors are Apple’s desktop and laptop computers with M1, M2, M3, and M4 chips.

Installation methods

There are two ways to install and use the ParaMonte library from MATLAB on your system:

The fast way

Download and untar/unzip the prebuilt MATLAB package for ParaMonte from the project repository’s release page on GitHub:
- For Windows with AMD64 (Intel) processor: libparamonte_matlab_windows_amd64.zip.
- For Linux with AMD64 (Intel) processor: libparamonte_matlab_linux_amd64.tar.gz.
- For macOS (Darwin) with AMD64 (Intel) processor: Follow the instruction below to download the ParaMonte MATLAB prebuilt library.
  Important: If you are a macOS user, we strongly recommend you to NOT download the library directly from the library's GitHub release page and NOT by clicking directly on the download links in web browsers. Instead, use the curl command line program in a Bash terminal to download the library from the GitHub release page. For example, open a Bash or zsh terminal on your macOS and execute the following commands to both download and decompress the ParaMonte MATLAB library,
```
curl -OL https://github.com/cdslaborg/paramonte/releases/download/2024.04.29/libparamonte_matlab_darwin_amd64.tar.gz
tar xvzf libparamonte_matlab_darwin_amd64.tar.gz && cd libparamonte_matlab_darwin_amd64
```
  The curl application is automatically installed on all macOS. If not, you can install it via Homebrew,
```
brew install curl
```
- For macOS (Darwin) with ARM64 processor (M1, M2, M3, M4, etc.): Follow the instruction below to download the ParaMonte MATLAB prebuilt library.
  Important: If you are a macOS user, we strongly recommend you to NOT download the library directly from the library's GitHub release page and NOT by clicking directly on the download links in web browsers. Instead, use the curl command line program in a Bash terminal to download the library from the GitHub release page. For example, open a Bash or zsh terminal on your macOS and execute the following commands to both download and decompress the ParaMonte MATLAB library,
```
curl -OL https://github.com/cdslaborg/paramonte/releases/download/2024.04.29/libparamonte_matlab_darwin_arm64.tar.gz
tar xvzf libparamonte_matlab_darwin_arm64.tar.gz && cd libparamonte_matlab_darwin_arm64
```
  The curl application is automatically installed on all macOS. If not, you can install it via Homebrew,
```
brew install curl
```
Follow further instructions below for the first-time usage.

The long way

If,

the ParaMonte prebuilt library is not available for your platform, or,
your system’s architecture is other than those supported by the pre-built libraries, or,
you are testing a ParaMonte library pre-release, or,
you are a professional programmer yearning to challenge your computer programming knowledge and skills,

then the last resort to install the ParaMonte MATLAB library is to build the library from scratch on your system. In such a case, you will have to follow the special instructions given for your platform on this website,

Important: Before proceeding to the platform-specific build instructions above, you must set up your MATLAB MEX compiler. To do so, open a ParaMonte-compatible MATLAB session which you intend to use with ParaMonte application later. Type the following command on the MATLAB command prompt:

mex -setup C

This command will set up the MATLAB MEX compiler for the C programming language. If necessary or desired, you can additionally set up the MATLAB MEX compiler for C++ and Fortran programming languages.

mex -setup C++
mex -setup Fortran

Beware that each MATLAB version release is only compatible with a handful of C, C++, and Fortran compilers. For information on this matter, consult the MATLAB documentation website for the MATLAB MEX compiler.

See also the pre-installation notes and the quick installation guidelines.

Once the library build and installation is complete, follow further instructions below for the first-time usage.

First-time usage

Either,
- open a ParaMonte-compatible MATLAB session as listed above from the Operating System’s search box, or,
- open a MATLAB session from the command line:
  - On Windows, open a CMD terminal that recognizes the MATLAB software.
  - On Linux, open a bash terminal or zsh terminal.
  - On macOS, open a zsh terminal.
  - Open a MATLAB session by calling it on the command line via,
    matlab
    Tip: If the matlab executable is not recognized by the bash/zsh terminal, see this page for a solution.
Once the MATLAB interactive environment opens, change the current working directory of MATLAB to the root directory of the ParaMonte library (where the ParaMonte library license file exists). You can do this on the MATLAB command prompt as,
```
cd path_to_the_root_directory_of_paramonte
```
where you will have to replace the path_to_the_root_directory_of_paramonte with the root path to the ParaMonte library on your system. The root path is the path to the directory where the ParaMonte LICENSE.md file exists.

Call the ParaMonte library for the first time via the following commands (simply type the commands on the MATLAB command prompt),

addpath('./', '-begin'); % add the ParaMonte library package root directory to MATLAB's list of search paths.
pm.lib.verify(); % verify the integrity of the ParaMonte library on your system (also searches for the relevant MPI library on your system).

If needed, follow any extra instructions provided by the library on your MATLAB command prompt.

You are all set! Enjoy the unification of simplicity, high-performance, parallelism, thoroughness, and advanced Monte Carlo algorithms and Machine Learning, all in one place. See the ParaMonte MATLAB documentation for detailed functionalities and examples.
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.

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.