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

The procedure for running Python 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 python main.py on a command prompt to run the Python script. Here, main is the name of the Python 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 Python simulations on the command-prompt

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

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

open a Python-aware terminal (e.g., the Anaconda3 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,
```
python main.py
```

Running Python simulations on the command-prompt on multiple processors

Important: To run MPI-parallel Python 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 Python library automatically asks for your permission to install any missing libraries on your system when you type

import paramonte as pm

for the first time in Python 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 Python session.

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

Tip: Note that the only difference between the above MPI-enabled Python script main_mpi.py and the corresponding serial Python script main.py 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 Python simulations in parallel.

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

open a Python-aware terminal (e.g., the Anaconda3 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 python main_mpi.py
```
  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 python main_mpi.py
```
  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.

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 Python simulations from within an IPython session

The procedures for running ParaMonte python simulations from within an IPython or Jupyter session, whether serial or parallel, are the same as the procedures for running Python simulations on the command-line, except that you need to add an exclamation mark (!) before the commands. For example,

!python main.py

in an IPython or Jupyter session is equivalent to,

python main.py

on a Bash terminal on Linux/macOS or an Anaconda3 command-prompt on Windows. So is the syntax for running MPI-enabled ParaMonte Python simulations from within IPython or Jupyter.

On Windows

!mpiexec -localonly -n 3 python main_mpi.py

On Linux / macOS
```
!mpiexec -n 3 python main_mpi.py
```

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.