There are two ways to use the ParaMonte library from C/C++/Fortran languages on Linux operating systems (OS):
- the fast way: using the prebuilt ParaMonte libraries for Linux, or,
- the long way: building ParaMonte from scratch on your system.
Using the prebuilt ParaMonte library
This is the fast way. Simply download the prebuilt ParaMonte libraries for Linux from the release page of the ParaMonte repository on GitHub for the configuration of your choice. If you are not familiar with the naming convention used for the ParaMonte library files, refer to the pre-installation notes before continuing.
Using the ParaMonte library prebuilt via the Intel compiler suite
If you still do not know which library configuration is the most appropriate for your needs, we recommend downloading and using the ParaMonte libraries prebuilt via the Intel compilers (even if you are using the GNU compilers to build your applications),
for usage from the C programming languages:
libparamonte_c_linux_x64_intel_release_shared_heap for serial simulations.
libparamonte_c_linux_x64_intel_release_shared_heap_impi.tar.gz for MPI-parallel simulations via the Intel MPI library.
for usage from the C++ programming languages:
libparamonte_cpp_linux_x64_intel_release_shared_heap.tar.gz for serial simulations.
libparamonte_cpp_linux_x64_intel_release_shared_heap_impi.tar.gz for MPI-parallel simulations via the Intel MPI library.
for usage from the Fortran programming language:
libparamonte_fortran_linux_x64_intel_release_shared_heap.tar.gz for serial simulations.
libparamonte_fortran_linux_x64_intel_release_shared_heap_impi.tar.gz for MPI-parallel simulations via the Intel MPI library.
Using the ParaMonte library prebuilt via the GNU compiler suite
If you want to build your applications exclusively via GNU compilers and MPICH MPI library, you can instead download the ParaMonte libraries prebuilt via the GNU Compiler Collection 10.1.0 and MPICH 3.2 MPI library, where applicable,
for usage from the C programming languages:
libparamonte_c_linux_x64_gnu_release_shared_heap.tar.gz for serial simulations.
libparamonte_c_linux_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.
libparamonte_c_linux_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.
for usage from the C++ programming languages:
libparamonte_cpp_linux_x64_gnu_release_shared_heap.tar.gz for serial simulations.
libparamonte_cpp_linux_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.
libparamonte_cpp_linux_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.
for usage from the Fortran programming language:
libparamonte_fortran_linux_x64_gnu_release_shared_heap.tar.gz for serial simulations.
libparamonte_fortran_linux_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.
libparamonte_fortran_linux_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.
Building the ParaMonte library locally on your system
This is the long way. Despite the scary name, the entire build process is super-straightforward and fully-automated, including the process of the compiler and MPI/Coarray library installations if they are missing on your system. Currently, building the ParaMonte library from scratch minimally requires either the GNU Compiler Collection or the Intel Parallel Studio installed on your system.
Steps to build the ParaMonte library on Linux:
(optional) Install a recent (version ≥ 8.4) GNU Compiler collection on your system, as well as the MPICH MPI library, version ≥ 3.2.Important: The ParaMonte build-script can automatically install all the missing prerequisite components (GNU compilers and MPI/Coarray parallelism libraries) on your system if needed, with your permission (. This automatic installation excludes the Intel C/C++/Fortran compilers as those are proprietary software and you will have to install them by yourself). If you intend to build the ParaMonte library from scratch on your system and you are not sure whether you have the compilers or the MPI libraries already installed on your system, leave this task to the ParaMonte install script.
If you intend to build Coarray-parallel applications, then you can optionally download and install the OpenCoarrays compiler wrapper on your system, or again, you can leave this task to the ParaMonte library build script to install it for you automatically. You can check which version of the GNU compilers, the MPI library, or OpenCoarrays
cafcompiler wrapper may be already installed on your system by trying the following commands in a Bash shell,
gcc (GCC) 10.1.0 Copyright (C) 2020 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
GNU Fortran (GCC) 10.1.0 Copyright (C) 2020 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
HYDRA build details: Version: 3.2 Release Date: Wed Nov 11 22:06:48 CST 2015
OpenCoarrays Coarray Fortran Compiler Wrapper (caf version 2.9.0) Copyright (C) 2015-2020 Sourcery Institute Copyright (C) 2015-2020 Sourcery, Inc. OpenCoarrays comes with NO WARRANTY, to the extent permitted by law. You may redistribute copies of OpenCoarrays under the terms of the BSD 3-Clause License. For more information about these matters, see the file named LICENSE that is distributed with OpenCoarrays.
If you know that these software already exist on your system, but the Bash terminal appears to not be able to recognize them, for example, by emitting the following message for
-bash: caf: command not found
one potential underlying cause could be that the path to the directory of the software is not part of the Bash environmental
PATHvariable.Tip: You can leave this compiler installation step to the ParaMonte library build scripts to install required GNU compilers, as well as the MPI / OpenCoarrays parallel libraries on your system, as explained below.
Alternatively, you can download and install the Intel Parallel Studio 2019 or newer on your systemNote: The Intel Parallel Studio and compilers are available free of charge to all students, teachers, and open-source software developers. Most recently Intel has made its entire suite of HPC compilers freely available to everyone.
If the installation is done properly, you should be able to confirm the version of your Intel Fortran compiler installation by the following command in a Bash shell environment,
ifort (IFORT) 184.108.40.206 20200306 Copyright (C) 1985-2019 Intel Corporation. All rights reserved.
- Download the latest source release of the ParaMonte source code from GitHub, then open a Bash terminal, navigate the directory containing the downloaded tar file and untar it via,
tar xvzf main.tar.gz cd paramonte-main
Call the Bash installation script
install.shon the command-line interface with the desired flags:
But before doing so, type the following command on the same Bash command line as before,
chmod +x ./install.sh
chmodensures that the build-script has executable permission on your system.
To speed up the build, you can specify the type of library you want to build by any of the following flags:
usage: ./install.sh \ -L <build library for: C C++ Fortran MATLAB Python> \ -s <compiler suite: intel gnu> \ -b <build mode: release testing debug> \ -l <library type: static shared (or equivalently, dynamic)> \ -p <parallelism type: none mpi cafsingle cafshared cafdistributed> \ -m <memory allocation type: stack heap> -t <ParaMonte test type: none basic sampler all> -x <ParaMonte example run enabled: true false> -c <generate code coverage report> \ -f <path to Fortran compiler> -M <path to mpiexec> -F <purge the existing prerequisite library installations and perform a fresh installation> -y <assume yes as answer to all installation permission inquiries> -B <perform GCC bootstrap installation> -n <default number of processors for parallel application> -h <help on the script usage> example: ./install.sh -L "Python C" -b "release debug" -l shared -p "none mpi" -m heap -n 3 or equivalently, ./install.sh --lang "Python C" --build "release debug" --lib shared --par "none mpi" --mem heap --nproc 3 The above two commands will build the library for the C and Python programming languages. flag definitions: -L | --lang : the ParaMonte library interface language(case-insensitive): C C++ Fortran MATLAB Python. the ParaMonte library will be built for usage from the user-specified languages. the default is "C C++ Fortran MATLAB Python". Note that CPP or cpp is also acceptable in place of C++. -s | --compiler_suite : the ParaMonte library build compiler suite: intel, gnu If you are not sure whether you have any of the two installed on your system, leave this option out. The script will automatically search for the appropriate compilers and libraries. If they are not found, it will ask for your permission to install the missing components. -b | --build : the ParaMonte library build type: release, testing, debug the default is "release testing debug". -l | --lib : the ParaMonte library type: static, shared (or equivalently, dynamic) the default is "shared" for all programming languages C/C++/Fortran/MATLAB/Python. -m | --mem : the ParaMonte library memory allocation type for arrays: stack, heap the default is "stack heap" resulting in builds for both stack and heap memory allocations. -p | --par : the ParaMonte library parallelism type: none mpi cafsingle cafshared cafdistributed the default is all parallelism options resulting in serial, MPI, and Coarray-parallel library builds. -t | --test : the ParaMonte library test type: none, basic, sampler, all. If basic, only the auxiliary non-sampler routines will be tested. If sampler, the ParaMonte sampler routines will be tested. If all, then all tests will be performed. The default is none. -x | --exam_enabled : the ParaMonte library examples run enabled?: true, false the default is true. -f | --fortran : path to Fortran compiler. If provided, the ParaMonte library will be built via the specified compiler. the default will be automatically determined. -M | --mpiexec : path to mpiexec routine. If provided, it will be used to find the MPI library. the default will be automatically determined. -F | --fresh : enables a fresh installation of all of the prerequisites of ParaMonte library. Applicable only to GNU compiler suite. -o | --local : prefer a build with the local installation of the prerequisites by ParaMonte (if they exist) over the default system settings. -D | --deploy : Copy also the library dependencies to the install directory of the library. This is a low level option and mostly useful for the developers of the ParaMonte library. Note for the developers: When building the ParaMonte library for dynamic programming languages for multiple build types with the --deploy flag, we recommend specifying the build types in this order: "debug testing release". -y | --yes-to-all : if a fresh installation of all of the prerequisites is needed, automatically answer yes to all permission requests. -B | --bootstrap : enables robust bootstrap build when building the required GCC version with an old GCC version. Applicable only to GNU compiler suite. -c | --codecov : perform code coverage analysis. This option will disable the ParaMonte examples builds and runs and the ParaMonte library installation. -d | --dryrun : skip a fresh library build and use the existing build to run the tests and examples and install the library (if any is possible). -a | --matdram : build (only) the ParaMonte MatDRAM MATLAB library and return. -n | --nproc : the default number of processes (coarray images) on which the ParaMonte examples/tests (if any) will be run: positive integer If not provided, 3 will be used. -h | --help : help with the script usage NOTE: All flags are optional. NOTE: If you specify multiple options for any flag, you must enclose all options together with quotation marks "". NOTE: Some flags conflict with each other: NOTE: The flag -m cafsingle or -m cafshared or -m cafdistributed cannot be specified with -L C or -L MATLAB or -L Python. NOTE: The flag -m cafsingle or -m cafshared or -m cafdistributed cannot be specified with -l shared (dynamically-linked library). NOTE: The flag -m stack (stack memory allocation) cannot be specified with -L MATLAB or -L Python.Tip: If you are not sure which build would be the most appropriate for your usage, we recommend the following configuration for serial ParaMonte simulations,
install.sh --lang LANGUAGE --build release --lib shared --mem heap --par noneand,
install.sh --lang LANGUAGE --build release --lib shared --mem heap --par mpifor MPI-parallel ParaMonte simulations, wherein both cases, you will have to replace the word LANGUAGE with the programming language of your choice: C (to build the ParaMonte C library), C++ (to build the ParaMonte C++ library), Fortran (to build the ParaMonte Fortran library), MATLAB (to build the ParaMonte MATLAB library), or Python (to build the ParaMonte Python library).
If you have multiple compiler suites (e.g., both Intel and GNU compilers) installed on your system and you wish to use one over the other to build the ParaMonte library, you can also specify the
--compiler_suiteflag on the command line. For example, to build the library via the Intel compilers,
install.sh --lang LANGUAGE --build release --lib shared --mem heap --par none -s intelor, to build the library via the GNU compilers,
install.sh --lang LANGUAGE --build release --lib shared --mem heap --par none -s gnu
For example, to build the ParaMonte Python library in release mode for both serial and parallel applications, try,
install.sh --lang python --build release --par "none mpi"
or, to build the ParaMonte MATLAB library in release mode for both serial and parallel applications, try,
install.sh --lang matlab --build release --par "none mpi"
or, to build shared ParaMonte C/C++ libraries in release mode for both serial and MPI-parallel applications, try,
install.sh --lang C --lib shared --mem heap --par "none mpi" --build release
or, to build a static ParaMonte Fortran library in both release and debug modes, with Coarray shared-memory parallelism enabled, for both heap and stack memory allocations, try,
install.sh --lang Fortran --lib static --par cafshared --mem "stack heap" --build "debug release"
or, to build the ParaMonte MatDRAM MATLAB library, try,
install.sh --matdramImportant: Note that multiple values specified for a build flag values are always separated by a white-space character and are enclosed together with quotation marks (“”), as in the examples above.Tip: By default, if you have both GNU and Intel compiler suites installed on your system, the ParaMonte build scripts will automatically build the library via the Intel compilers. To override this default behavior and build the library via the GNU compilers, you can specify either the
--compiler_suite gnubuild flag when calling the build script. For example, to build the ParaMonte C/C++ library in release mode as a shared library for both serial and MPI-parallel applications via the GNU compilers, try,
install.sh --lang C --lib shared --mem heap --par "none mpi" --build release -s gnu
You can also simply try,
to build the ParaMonte library for all possible configurations for all supported languages.Warning: Calling the
install.shscript with no flags will build the entire ParaMonte library for all three build modes (
debug) for all interface languages that are currently supported (
Python, ... ) for all parallelization modes (
cafdistributed) for the two types of memory allocations (
heap) for the two different library types (
shared). Depending on your system specifications, this can be a very lengthy process, typically taking a few hours or more to finish.Note: If you’d like to see a build flag that is not currently provided in the above list of flags, (for example, the type of or the method of linking against the compiler libraries), please let us know and we will try to add the requested features to the installation scripts in a new release of the ParaMonte library.
install.shscript initiates the build process and generates a folder named
buildin the root directory of the ParaMonte repository which will contain all build files. The final library files together with the example scripts will be installed in a separate folder named
binin the same root directory of the ParaMonte project that you have downloaded from GitHub.
- Congrats! You have now built and (locally) installed the ParaMonte library for the configuration and language(s) of your choice on your system. Check out the two new folders
binthat have been automatically created by the install script in the root directory of the uncompressed ParaMonte repository that you have downloaded. Inside the
bindirectory, you will see all the different build subdirectories corresponding to the different ParaMonte library build configurations. For example,
install.sh --lang C++ --build release --lib shared --mem heap --par mpi -s intel
will generate the following subdirectory,
install.sh --lang C++ --build release --lib shared --mem heap --par mpi -s gnu
will generate either of the following subdirectories,
in the bin directory of the ParaMonte library, depending on the existing MPI library installed on the system (Intel MPI vs. MPICH vs. OpenMPI). Any of these subdirectories contains the ParaMonte library files along with an example simulation source file and a build-script that can build the example to generate the executable, as well as a
README.mdfile explaining how to build the supplied example.