There are two ways to use the ParaMonte library from C/C++/Fortran languages on Linux operating systems (OS):

  1. the fast way: using the prebuilt ParaMonte libraries for Linux, or,
  2. 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.

If you still do not know which library configuration is the most appropriate for your needs, we recommend downloading,

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 9.1.0 and MPICH 3.2 MPI library, where applicable,

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:

  1. (optional) Install a recent (version >7.0.0) GNU Compiler collection on your system, as well as the MPICH MPI library, version >3.2.

    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 caf compiler wrapper may be already installed on your system by trying the following commands in a Bash shell,

    gcc --version
    
    gcc (GCC) 7.3.0
    Copyright (C) 2017 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.
    
    gfortran --version
    
    GNU Fortran (GCC) 7.3.0
    Copyright (C) 2017 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.
    
    mpiexec --version
    
    HYDRA build details:
    Version:                                 3.2
    Release Date:                            Wed Nov 11 22:06:48 CST 2015
    
    caf --version
    
    OpenCoarrays Coarray Fortran Compiler Wrapper (caf version 2.8.0)
    Copyright (C) 2015-2018 Sourcery Institute
    Copyright (C) 2015-2018 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 caf,

    -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 PATH variable.

    Alternatively, you can download and install the Intel Parallel Studio 2018 or newer on your system

    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 --version
    
    ifort (IFORT) 18.0.2 20180210
    Copyright (C) 1985-2018 Intel Corporation.  All rights reserved.
    
  2. 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 paramonte-master.tar.gz
    cd paramonte-master
    
  3. Call the Bash installation script install.sh on 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
    

    The command chmod ensures 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:

    install.sh --help
    
        
    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 dynamic> \
        -p <parallelism type: none mpi cafsingle cafshared cafdistributed> \
        -m <memory allocation type: stack heap>
        -t <ParaMonte test run enabled: true false>
        -x <ParaMonte example run enabled: true false>
        -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 dynamic -p "none mpi" -m heap -n 3
    
        or equivalently,
    
        ./install.sh --lang "Python C" --build "release debug" --lib dynamic --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".
        -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, dynamic
                                  the default is "dynamic static" for C/C++/Fortran languages and "dynamic" for 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_enabled     : the ParaMonte library test run enabled?: true, false
                                  the default is true.
        -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.
        -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.
        -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 dynamic (dynamically-linked library).
    NOTE:     The flag -m stack (stack memory allocation) cannot be specified with -L MATLAB or -L Python.
    
    
    

    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 dynamic ParaMonte C/C++ libraries in release mode for both serial and MPI-parallel applications, try,

    install.sh --lang C --lib dynamic --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 --matdram
    

    You can also simply try,

    install.sh
    

    to build the ParaMonte library for all possible configurations for all supported languages.

    The install.sh script initiates the build process and generates a folder named build in 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 bin in the same root directory of the ParaMonte project that you have downloaded from GitHub.

  4. 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 build and bin that have been automatically created by the install script in the root directory of the uncompressed ParaMonte repository that you have downloaded. Inside the directory, 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 dynamic --mem heap --par mpi -s gnu

will generate the following subdirectory,

./bin/libparamonte_cpp_linux_x64_gnu_release_dynamic_heap_mpi

in the root directory of the ParaMonte library. This subdirectory contains the ParaMonte binary files along with an example and a build-script that can build the example to generate the executable, as well as a README.md file explaining how to build the supplied example.


If you have any questions about the topics discussed on this page, feel free to ask in the comment section below or reach out to the ParaMonte library authors.