Running the ParaMonte C/C++/Fortran applications | ParaMonte: Parallel Monte Carlo Library

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 the executable generated by the quick automated approach

If you have used the application build-scripts provided along with each of the prebuilt ParaMonte libraries to build your C/C++/Fortran application, you can follow the guidelines below to run your application.

Running the executable generated via the quick automated approach on Windows

The current version of the Batch build-script build.bat that comes with the prebuilt ParaMonte libraries, both builds and runs your application.

Note: If the ParaMonte library that you are using has been built for parallel simulations and you intend to run your application in parallel, then you can set the runtime number of processors to be used for your simulation (for example, 2, in the following command) via,

set nproc=2

This assignment must be done before calling the build-script. If you do not set a value for nproc, the default value of 3 will be used by the build script to run your parallel application.

To rerun an executable, follow the instructions below on this page for serial and parallel simulations.

Running the executable generated via the quick automated approach on Linux / macOS

The current version of the Bash build-script build.sh that comes with the prebuilt ParaMonte libraries, generates another Bash script run.sh (in the same working directory) which can be called on the command-line to run the generated executable.

./run --nproc 2

or,

./run -n 2

This will run your parallel application on two processors. The default value for the number of processors is 3 in the build-script.

Tip: There are a several options that can be specified at the time of calling the build.sh script, including the option to set the default number of MPI- or Coarray- parallel tasks. To get help on the options, try,

./build.sh -h

or,

./build.sh --help

Running the manually-generated executable via do-it-yourself approach

The instructions slightly vary across different Operating Systems (OS), depending on the parallelism-paradigm used in your application.

Running the manually-generated executable on a single processor

To run an executable (main.exe) built for serial simulations on either Windows, Linux, or macOS (Darwin), simply type the executable’s name on the command line,

main.exe

Running the manually-generated executable on 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 the manually-generated executable on multiple processors on Windows

MPI-parallelism
To run an executable (main.exe) built for MPI-parallel-simulations on a single node of multiple processors, for example on a single computer, invoke the MPI launcher mpiexec on the command line,
```
mpiexec -localonly -n 3 main.exe
```
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.
Coarray-parallelism
- Set the number of parallel images (that is, the number of processors or parallel tasks) with which you want to run your application. Assuming you have built your application via the Intel Parallel Studio compilers, you can request a specific number of runtime processors by (re)defining the FOR_COARRAY_NUM_IMAGES environmental variable on the command-prompt. For example to run a coarray-enabled ParaMonte application on 3 processors,
```
set FOR_COARRAY_NUM_IMAGES=3
```
  If this variable is undefined at runtime, the application will, by default, use all of the available processors on the system for the parallel simulation.
- Run the Coarray-enabled parallel ParaMonte application by simply calling the executable’s name on the command line,
```
main.exe
```

Running the manually-generated executable on multiple processors on Linux / macOS

MPI-parallelism
To run an executable (main.exe) built for MPI-parallel-simulations on multiple processors, invoke the MPI launcher mpiexec on the command line,
```
mpiexec -n 3 main.exe
```
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.
Coarray-parallelism
Running Coarray-enabled parallel applications on Unix-like systems depends on the choice of compiler you have made to build your application.
- To run Coarray-parallel applications built via the Intel Parallel Studio tools, see the Intel’s tutorial page on the Coarray usage.
- To run Coarray-parallel applications built via the OpenCoarrays, you should use the dedicated OpenCoarrays launcher cafrun. For more information, visit the OpenCoarrays development page on GitHub.

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.