ParaMonte pre-installation notes

Naming convention used for ParaMonte library builds

The ParaMonte core library file in all programming languages is always named libparamonte.<suffix> where <suffix> is replaced with platform-specific suffix based on the library type determined by the compiler.
The following table illustrates the common library suffixes used on different platforms.

The ParaMonte binary folder naming follows a universal naming convention across all programming languages and platforms.

• The generated binary folders (containing the ParaMonte library and its examples) have the following pattern for compiled languages (C, C++, Fortran),

  libparamonte_<interface language: c/cpp/fortran/...>_<OS: windows/linux/darwin/...>_<architecture: amd64/arm64/...>_<compiler vendor and major version: intel2021/gnu13/...>_<build type: native/tuned/ipo/release/testing/debug>_<library type: shared/static>_<memory allocation type: stack/heap>_<parallelism library/type: serial/mpi/impi/mpich/openmpi/openmp/cafsingle/cafshared/cafdist/...>_<runtime checking mode: checked/nocheck>  
  

• and the generated binary folders (containing the ParaMonte library and its examples) have the following pattern for interpreted languages (MATLAB, Python, R, etc.),

  libparamonte_<interface language: c/cpp/fortran/...>_<OS: windows/linux/darwin/...>_<architecture: amd64/arm64/...>  
  

where,

• programming language can be either:
  • c: indicating a library build meant to be called and used from C or C-complaint main applications.
  • cpp: indicating a library build meant to be called and used from C++ main applications.
  • fortran: indicating a library build meant to be called and used from Fortran main applications.
  • matlab: indicating a library build meant to be called and used from MATLAB main applications.
  • python: indicating a library build meant to be called and used from Python main applications.
  • r: indicating a library build meant to be called and used from R main applications.
• operating system type can be either:
  • windows: indicating a library that can only be used on Windows OS, or,
  • darwin: indicating a library that can only be used on macOS, or,
  • linux: indicating a library that can only be used on Linux OS, or,
  • some other name (or unknown if it cannot be identified), indicating a library build meant to be used on the specific OS for which the library has been built.
  Note: The ParaMonte build-scripts have only been tested on Windows, Linux, and Darwin operating systems. However, it should be possible to build ParaMonte on any other platform or architecture on which 1. the GNU compiler Collection or the Intel Parallel Studio can be installed, 2. a Unix Bash script or a Windows Bash script can run.
• architecture type can be either:
  • amd64: indicating a library built for the x86-64 architecture (also known as x64, x86_64, AMD64, and Intel 64), a 64-bit version of the x86 instruction set, first announced in 1999.
  • arm64: indicating a library that is built for arm64 architecture, also known as AArch64 or ARM64, a 64-bit extension of the ARM architecture family (M1, M2, M3 macOS chips).
  • Some other architecture (or unknown if it cannot be identified) indicates a library build that is meant to be used on the specific architecture for which the library has been built.
• compiler suite can be any ParaMonte-compatible compiler vendor name you use to build the ParaMonte library. Currently, the ParaMonte build-scripts have only been tested with:
  • intel: on Windows and Linux OS for both serial and parallel ParaMonte library builds, as well as on Darwin (macOS) on amd64 chip, but only for serial ParaMonte library builds,
    Important: The minimum Intel compiler versions required for building the ParaMonte library from the source are,
    

    • Intel icx / ifx / ifort ≥ 2021.8.0 on Linux,
    • Intel icx / ifx / ifort ≥ 2021.8.0 on Windows,
    • Intel icx / ifx / ifort ≥ 2021.8.0 on macOS (Darwin),
  • gnu: on Windows, Linux, and Darwin OS for both serial and parallel ParaMonte library builds.
    Important: The minimum GNU compiler versions required for building the ParaMonte library are GNU gcc / g++ / gfortran > 10.3.0.
• build type can be either:
  • native: indicating a build targeting the current CPU architecture (leading to potentially non-portable binary), or,
  • tuned: indicating a build targeting a family of CPU architectures supported by the compiler (leading to potentially very large binary), or,
  • ipo: indicating an interprocedurally-optimized build targeting the current CPU architectures supported by the compiler, or,
  • release: indicating a build with compiler flags that ensure the fastest possible simulations at runtime while remaining broadly portable, or,
  • testing: indicating a build with compiler default optimization flags used only for testing purposes, or,
  • debug: indicating a build with compiler flags that enable tracing of any compile-time or run-time errors.
  Tip: If you are unsure which one is appropriate for your case, always choose release. Generally, the debug and testing build types are mostly useful to developers and professional programmers. In some cases where the code consistently crashes in the release mode, it may be useful to run the same simulation using a debug library build to trace the source of the runtime error in the code.
• library type can be either:
  • shared: indicating a dynamically-linked ParaMonte library build, or,
  • static: indicating a statically-linked (archive) ParaMonte library build.
  Tip: If you are unsure which library type is suitable, choose shared over static ParaMonte library builds.
• memory allocation type can be either:
  • stack: indicating static allocation of all automatic arrays and arrays created for temporary computations on the stack, or,
  • heap: indicating heap allocation of all automatic arrays and arrays created for temporary computations on the heap).
  Tip: In general, stack memory allocation can lead to slightly more efficient codes than heap memory allocation. However, applications that use the stack for temporary memory allocations often run into the stack overflow kind of errors caused by the application reaching its maximum stack memory usage limit set by the operating system. While the stack size for an application can often be increased on both Windows and Unix-like OS, it can be potentially a challenging task for programmers with insufficient experience. Therefore, if you do not know the difference between stack vs. heap memory allocation, always choose heap-enabled ParaMonte library builds to avoid unexpected stack overflow errors.
• parallelism type can be either:
  • serial: indicating no parallelism, that is, a library built for serial simulations, or,
  • openmp: indicating a library built via the OpenMP standard for shared-memory (thread-based) parallelism, or,
  • mpi: indicating a library built via (some unknown brand) Message Passing Interface (MPI) that is meant to be linked against parallel main applications for parallel simulations via MPI, or,
  • impi: indicating a library built via the Intel Message Passing Interface (MPI) that is meant to be linked against parallel main applications for parallel simulations via Intel MPI, or,
  • mpich: indicating a library built via the MPICH Message Passing Interface (MPI) that is meant to be linked against parallel main applications for parallel simulations via MPICH MPI, or,
  • openmpi: indicating a library built via the OpenMPI Message Passing Interface (MPI) that is meant to be linked against parallel main applications for parallel simulations via OpenMPI, or,
  • cafsingle: indicating a library built via Coarray Fortran parallelism paradigm that is meant to be linked against Coarray parallel main applications optimized and usable for serial simulations only (i.e., no parallelization), or,
  • cafshared: indicating a library built via Coarray Fortran parallelism paradigm that is meant to be linked against Coarray parallel main applications for Coarray-enabled parallel simulations on shared-memory architecture, or,
  • cafdist: indicating a library built via Coarray Fortran parallelism paradigm that is meant to be used for Coarray-enabled parallel simulations on distributed-memory architecture, or,
  Warning: The Coarray parallelism is currently under development in the new ParaMonte 2 release of the library.
  Warning: The three Coarray parallelism options are only available when the ParaMonte library is compiled via the Intel Fortran compiler. When compiled via the GNU Fortran compiler, the only option is cafsingle. When compiled via the GNU Fortran compiler with OpenCoarrays library, the sole option is cafdist. Also, the Coarray-enabled parallel ParaMonte libraries can only be built as static (archive) libraries. Also, the Coarray parallelism is exclusively available for ParaMonte library builds that are meant to be statically linked against main applications exclusively written in Fortran.
• runtime checking mode can be either:
  • checked: indicating all runtime memory-bound input argument sanity checks are enabled (which is useful for testing but can slow down the code), or,
  • nocheck: indicating all runtime memory-bound input argument sanity checks are disabled (which is the default behavior for production release code), or,

Supported platform and architecture

The ParaMonte library is currently developed with the presumption that it will be used on Windows/Linux/macOS operating systems (OS) built on an amd64 architecture system (also known as x64 on Windows and x86_64 on Linux and macOS). There is, however, no technical or programming barrier to building ParaMonte for other architectures as long as compatible MPI and Fortran/C compilers are available on the specific platform and architecture of interest.

Why are the prebuilt ParaMonte libraries available only for amd64 and arm64 architectures?

As of 2020, the amd64 and arm64 processor architectures takes the lion’s share of the market demand (illustrated in the figure below). It is costly for the ParaMonte developers (in terms of energy, money, and time) to build and release the library for all available architectures in the market. Note, however, that the library can be built on any architecture as long as a ParaMonte-compatible C/Fortran compiler can be installed on the system.

How can I find out the platform and architecture of my system?

• On Windows OS, open a Windows command-line interface (cmd.exe).
  • To find out your system’s OS, type,

    echo %OS%
    

    which should result in an answer like the following,

    Windows_NT
    

  • To check your system’s platform/architecture, type,

    echo %PLATFORM%
    

    which should result in an answer like the following,

    x64
    

    or,

    echo %PROCESSOR_ARCHITECTURE%
    

    which should result in an answer like the following,

    AMD64
    

    if your system’s architecture is amd64.
    
    

• On Unix-like OS (Linux/macOS), open a Bash shell.
  • To find out your system’s OS, type,

    uname -s
    

    which should result in an answer like the following,

    Linux
    

    or,

    Darwin
    

    depending on the type of your OS.

  • To check your system’s platform/architecture, type,

    uname -m
    

    which should result in an answer like the following,

    x86_64
    

    if your system’s architecture is amd64.