DOCSEARCHbyAlgolia
Submit Docs

ParaMonte

repository·main·Indexed 43 days ago

https://github.com/cdslaborg/paramonte

A high-performance library for Parallel Monte Carlo simulations and Machine Learning tasks in scientific inference, emphasizing automation, scalability, and cross-language interoperability. It includes a comprehensive CMake string utility library featuring functions such as format(), string_replace(), string_split(), and string_normalize().

Tokens
37.7K
Snippets
110
Records
122
Agent score
54%

What's inside ParaMonte

  1. Overview of ParaMonte

    main

    ParaMonte is a library of Monte Carlo routines for sampling mathematical density functions of arbitrary dimensions and Machine Learning (ML) algorithms for scientific inference. It is designed for high-performance, scalable, and automated simulations across multiple platforms.

    Key features include:

    • Automation: Minimal time investment for building, running, and post-processing.
    • Interoperability: Support for C, C++, Fortran, MATLAB, and Python.
    • Parallelism: Support for shared-memory OpenMP threads and MPI/Coarray distributed communications with zero-parallel-coding effort required from the user.
    • Reproducibility: Fully-deterministic reproducibility and automatic restart functionality.
    • Zero-dependence: Core library has no external third-party dependencies (except optional MPI for parallel simulations).

  2. Overview of ParaMonte external repositories

    main

    The external/ directory contains auxiliary GitHub projects and libraries used to support ParaMonte. These repositories provide documentation, code-coverage resources, and specific library clones used by the project.

    • OpenBLAS: A clone of the OpenBLAS library.
    • paramontec: Resources for ParaMonte code coverage.
    • paramonted: Resources for ParaMonte documentation.

  3. Configure TIER-4 ParaMonte library build flags for Fortran kind types

    main

    Advanced users and developers can use TIER-4 build flags to control which Fortran intrinsic kind type parameters are included in the ParaMonte library build. By specifying only the necessary kinds, you can reduce the final library size and decrease compilation times.

    These flags accept a semicolon-separated list of indices corresponding to the constant vectors in the Fortran iso_fortran_env intrinsic module (e.g., character_kinds(:), integer_kinds(:), etc.).

    Constraints and Warnings:

    • Limit: You can specify a maximum of five indices per type.
    • Compatibility: Some ParaMonte algorithms require compatible complex and real kinds. If you customize one, you may need to ensure the other uses compatible kind type parameters.
    • Minimum Requirements: When overriding defaults, you must ensure you include the minimally-required indices for your compiler to avoid breaking functionality.

  4. Configure MPI Parallelism in ParaMonte

    main

    ParaMonte supports distributed parallelism via the Message Passing Interface (MPI). While the core library has zero dependencies, an MPI runtime is required for MPI-parallel simulations.

    Recommended MPI Runtimes

    • Windows and Linux: It is highly recommended to use Intel MPI runtime libraries. Note that Intel MPI requires the ParaMonte library to have been prebuilt using Intel compilers.
    • macOS and Linux: You can use Open-MPI or MPICH.

    Dependency Compatibility Matrix

    DependencyWindows (amd64)Linux (amd64)macOS (amd64)macOS (arm64)
    Intel MPI (IMPI) >= 2021.8✅✅❌❌
    MPICH MPI (MMPI) >= 3❌✅✅✅
    OpenMPI (OMPI) >= 4❌✅✅✅

  5. Build ParaMonte using CMake on Unix, WSL, or POSIX terminals

    main

    To build ParaMonte on Linux, macOS, WSL, or any POSIX-style terminal (Bash, MSYS2, Git Bash), ensure you have CMake (>3.16), GNU Make, and a Fortran 2008-compliant compiler (e.g., gfortran >10, ifort >2021, or ifx >2024).

    Build Steps

    1. Navigate to the ParaMonte root directory.
    2. Create and enter a build directory.
    3. Configure the project using the appropriate generator for your environment:
      • Windows MinGW (e.g., Git Bash): Use MinGW Makefiles and specify the Fortran compiler path.
      • Windows MSYS2: Use MSYS2 Makefiles and specify the Fortran compiler path.
      • Linux/macOS/WSL: Use Unix Makefiles and specify the Fortran compiler path.
    4. Run make to compile.
    5. Run make install to install the library into the lib subdirectory within the build folder.

    Optional Post-Build Tasks

    • Deploy: make deploy (moves library to the pre-specified deployment folder).
    • Test: make test (runs tests if enabled during configuration). 0- Examples: make example (builds and runs examples if enabled).
    • Benchmarks: make benchmark (builds and runs benchmarks if enabled).

    Note on Windows Make commands

    • In MSYS2, you may need to install the GNU make software.
    • In MinGW, you may need to install mingw32-make. If the command is named mingw32-make, you must use that name or rename the binary to make before running it.
    # For Unix-compatible environments (Linux, macOS, WSL)
mkdir build; cd build && cmake -G "Unix Makefiles" .. -Dfc="$(command -v gfortran)" && make && make install

  6. Prerequisites for building ParaMonte

    main

    Before running install.sh, ensure your system meets the following requirements:

    1. CMake

    A recent version (>2018) of CMake must be installed and available in your PATH.

    2. C and Fortran Compilers

    You need C and Fortran compilers that minimally support Fortran 2008.

    EnvironmentRecommended Compilers
    LinuxGNU or Intel
    macOSGNU or NAG (NAG is untested)
    WSL, MSYS2, MinGWGNU or Intel

    Compiler-specific notes:

    • Intel Compilers: Requires a recent version (>2023) of Intel OneAPI and HPC Toolkits.
    • GNU Compilers: Requires a recent version (>10) of GNU C and Fortran compilers.

    3. MPI Libraries (for MPI-parallelism)

    If you require MPI support, you must have one of the following installed:

    • Intel MPI: Use with Intel compilers (included in Intel OneAPI + HPC suite).
    • MPICH: Use with GNU compilers.
      • Ubuntu: sudo apt install mpich
      • macOS: brew install mpich && brew link mpich
    • Open-MPI: Use with GNU compilers.
      • Ubuntu: sudo apt install openmpi-bin openmpi-common libopenmpi-dev
      • macOS: brew install openmpi && brew link openmpi
    • Microsoft MPI: Available for Windows/GNU, but ParaMonte has not been tested against it and Fortran bindings are uncertain.

  7. Use ParaMonte build configuration flags with install scripts

    main

    You can customize the ParaMonte library build by passing optional flags to the install.sh (Linux/macOS) or install.bat (Windows) scripts.

    Syntax:

    ./install.sh --flag value

    Key details:

    • You can specify multiple --flag value pairs in a single command.
    • For install scripts, many flags (like lang, lib, mem, and par) accept a semi-colon-separated list of values to build multiple versions of the library in a specific order.
    • If install.sh is not executable, run chmod +x install.sh first.
    ./install.sh --flag value

  8. Install ParaMonte via install.sh script

    main

    On macOS and Linux systems, the recommended way to build ParaMonte is using the install.sh Bash script located in the repository root. This script acts as a convenience wrapper around CMake to automate the installation process.

    To run the installation, use the following command structure, replacing TARGET_LANGUAGE with the programming language you intend to use to access the library:

    ./install.sh --lang TARGET_LANGUAGE

    Output Redirection and Background Execution

    If you want to capture the installation logs or run the process in the background, use these patterns:

    • Redirect output to a file:
      ./install.sh --lang TARGET_LANGUAGE > install.sh.out 2>&1
    • Run in the background:
      ./install.sh --lang TARGET_LANGUAGE > install.sh.out 2>&1 &
    • Run in the background and disown (prevent termination when terminal closes):
      ./install.sh --lang TARGET_LANGUAGE > install.sh.out 2>&1 & jobs; disown
    ./install.sh --lang c

  9. Install ParaMonte libraries for C, C++, Fortran, or MATLAB

    main

    ParaMonte provides installation scripts for Windows (install.bat) and Unix-based systems (install.sh). You must specify the target language using the --lang flag.

    Prerequisites:

    • CMake > 3.21
    • Intel compiler > 2021 OR GNU compiler > 10
    • For MPI-parallel builds, ensure a relevant MPI library is installed on your system.

    Parallelism: To enable MPI parallelism, add the --par mpi flag to your installation command.

    # Unix (Bash) installation examples
./install.sh --lang c
./install.sh --lang cpp
./install.sh --lang fortran
./install.sh --lang matlab
./install.sh --lang c --par mpi

# Windows (CMD) installation examples
install.bat --lang c
install.bat --lang cpp
install.bat --lang fortran
install.bat --lang matlab
install.bat --lang c --par mpi

  10. Prerequisites for Windows Installation

    main

    To successfully run install.bat, ensure the following components are installed and accessible in your system PATH:

    1. CMake: Version >2018.
    2. C + Fortran Compilers: Must support Fortran 2008.
      • Option A: Intel Compiler Collection (Recommended/Tested)
        • Microsoft Visual Studio (>2020) with C++ development tools.
        • Intel OneAPI Base Toolkit (>2023).
        • Intel OneAPI HPC Toolkit (>2023).
        • Note: Use the Intel Command Prompt from the Start Menu to run the installation.
      • Option B: GNU Compiler Collection
        • GNU C/C++/Fortran compilers (>10).
        • An MPI library (e.g., Microsoft MPI), though only Intel MPI is currently tested.
        • Note: Use the Intel Command Prompt or the x64 Native Tools Command Prompt for VS.
    3. Repository Access: Navigate to the folder containing the ParaMonte repository before running the script.

  11. Install ParaMonte

    main

    You can install ParaMonte using one of two methods:

    1. Prebuilt Libraries (Recommended)

    Download ready-to-use libraries from the GitHub release page. Each prebuilt library includes example codes and build scripts.

    2. Build from Source

    You can build the library from the source in the GitHub repository. The build process is automated for all supported languages.

    Supported Compiler Suites for Source Builds:

    • GNU Compiler Collection >= 10.3: Supported on Windows (amd64), Linux (amd64), macOS (amd64), and macOS (arm64).
    • Intel OneAPI >= 2021.8.0: Supported on Windows (amd64), Linux (amd64), and macOS (amd64). (Not supported on macOS arm64).

    Essential Build System:

    • CMake >= 3.21 is required for all platforms.

  12. Prepare ParaMonte examples for use

    main
    The examples located in the example/ directory are not standalone. Before you can run them, you must build them using the appropriate installation scripts found in the root directory of the ParaMonte project. This ensures the examples are correctly linked to your installed ParaMonte environment.