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

  1. the fast way: using the prebuilt ParaMonte libraries for Darwin, or,
  2. the long way: building ParaMonte from scratch on your system.

The compile-time and runtime prerequisites

Regardless of which ParaMonte installation method you choose from the above, you will need some compilers and libraries to link your C/C++/Fortran applications against the ParaMonte library and build your executable, or to run the executable. You likely have many, if not all, of these prerequisites already installed on your system,

  • A C/C++ compiler, if you intend to link C/C++ code against the ParaMonte library. Possible compiler options are the Intel C/C++ compiler icc, the macOS’ default C/C++ compiler front-end clang, and the GNU C/C++ compilers (gcc/g++).
  • A Fortran compiler, if you intend to link Fortran code against the ParaMonte library or build the ParaMonte library from scratch on your system. Possible compiler options are the Intel Fortran compiler ifort (version ≥ 2019.1.1) and the GNU Fortran compiler gfortran (version 10.2.0).
  • The Open-MPI library (version ≥ 4.0.5), if you intend to use the prebuilt ParaMonte libraries to build MPI-parallelized C/C++/Fortran applications or if you intend to build the MPI-parallel ParaMonte library from scratch on your system.
  • The MPICH library (version ≥ 3.2), if you intend to build the MPI-parallel ParaMonte library from scratch on your system and for some reason do not want to install and use the Open-MPI library.
  • The OpenCoarrays library (version 2.9.0 or newer) if you intend to use the prebuilt ParaMonte libraries to build Coarray-parallelized Fortran applications or if you intend to build the Coarray-parallel ParaMonte library from scratch on your system.
  • A recent version of the Cmake software (version 3.14.0 or newer) if you intend to build the ParaMonte library from scratch on your system.

Using the prebuilt ParaMonte library

This is the fast way. Simply download the prebuilt ParaMonte libraries for Darwin 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_darwin_x64_intel_release_shared_heap for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_c_darwin_x64_intel_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

  • for usage from the C++ programming languages:

    • libparamonte_cpp_darwin_x64_intel_release_shared_heap.tar.gz for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_cpp_darwin_x64_intel_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

  • for usage from the Fortran programming language:

    • libparamonte_fortran_darwin_x64_intel_release_shared_heap.tar.gz for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_fortran_darwin_x64_intel_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

Using the ParaMonte library prebuilt via the GNU compiler suite

If you want to build your applications exclusively via the GNU compilers or you want to build parallel applications (which requires the Open-MPI library), you can instead download the ParaMonte libraries prebuilt via the GNU Compiler Collection ≥ 10.2.0 and Open-MPI ≥ 4.0.5 library, where applicable,

  • for usage from the C programming languages:

    • libparamonte_c_darwin_x64_gnu_release_shared_heap.tar.gz for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_c_darwin_x64_gnu_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_c_darwin_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_c_darwin_x64_gnu_release_shared_heap_mpich
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_c_darwin_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_c_darwin_x64_gnu_release_shared_heap_openmpi
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

  • for usage from the C++ programming languages:

    • libparamonte_cpp_darwin_x64_gnu_release_shared_heap.tar.gz for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_cpp_darwin_x64_gnu_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_cpp_darwin_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_cpp_darwin_x64_gnu_release_shared_heap_mpich
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_cpp_darwin_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_cpp_darwin_x64_gnu_release_shared_heap_openmpi
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

  • for usage from the Fortran programming language:

    • libparamonte_fortran_darwin_x64_gnu_release_shared_heap.tar.gz for serial simulations.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_fortran_darwin_x64_gnu_release_shared_heap
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_fortran_darwin_x64_gnu_release_shared_heap_mpich.tar.gz for MPI-parallel simulations via the MPICH MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_fortran_darwin_x64_gnu_release_shared_heap_mpich
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

    • libparamonte_fortran_darwin_x64_gnu_release_shared_heap_openmpi.tar.gz for MPI-parallel simulations via the OpenMPI MPI library.

      Here are the library download, untar, building, and running commands altogether,

      libname=libparamonte_fortran_darwin_x64_gnu_release_shared_heap_openmpi
curl -OL https://github.com/cdslaborg/paramonte/releases/download/v1.5.1/$libname.tar.gz
tar xvzf $libname.tar.gz && cd $libname
./build.sh && ./run.sh

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 Darwin:

  1. (optional) Install a recent (version ≥ 8.4) GNU Compiler collection on your system, as well as the Open-MPI library, version ≥ 4.0.5.

    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 (Homebrew GCC 10.2.0) 10.2.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

    gfortran --version

    GNU Fortran (Homebrew GCC 10.2.0) 10.2.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.

    mpiexec --version

    mpiexec (OpenRTE) 4.0.5

Report bugs to http://www.open-mpi.org/community/help/

    caf --version

    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 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 Fortran Compiler 2019 or newer on your system, if you intend to build only serial (non-parallel) applications. If you intend to build C/C++ applications, then you may also optionally download and install the Intel C/C++ compiler on your Mac separately.

    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) 19.1.0.216 20200306
Copyright (C) 1985-2019 Intel Corporation.  All rights reserved.
  2. Download the latest 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

  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 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> \
    -j <default number of processors for parallel library build> \
    -h <help on the script usage>

example:

    ./install.sh -L "Python C" -b "release debug" -l shared -p "none mpi" -m heap -n 3 -j 4

    or equivalently,

    ./install.sh --lang "Python C" --build "release debug" --lib shared --par "none mpi" --mem heap --nproc 3 --njob 4

    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.
    -j | --njob             : the default number of processes to be used for building the ParaMonte library. The default is 1.
    -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.

    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 --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 bin 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 shared --mem heap --par mpi -s intel

    will generate the following subdirectory,

    ./bin/libparamonte_cpp_darwin_x64_intel_release_shared_heap_impi

    or,

    ./install.sh --lang C++ --build release --lib shared --mem heap --par mpi -s gnu

    will generate either of the following subdirectories,

    ./bin/libparamonte_cpp_darwin_x64_gnu_release_shared_heap_mpich
./bin/libparamonte_cpp_darwin_x64_gnu_release_shared_heap_openmpi

    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.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 raise an issue on the GitHub page of the library, or reach out to the ParaMonte library authors.