{"id":19706057,"url":"https://github.com/llnl/parelagmc","last_synced_at":"2026-06-14T05:32:51.739Z","repository":{"id":66082968,"uuid":"116409954","full_name":"llnl/parelagmc","owner":"llnl","description":"Parallel element agglomeration multilevel Monte Carlo library.","archived":false,"fork":false,"pushed_at":"2018-06-20T16:10:41.000Z","size":299,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-06-14T05:32:51.115Z","etag":null,"topics":["monte-carlo","parallel","parallel-computing","simulation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/llnl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-05T17:27:34.000Z","updated_at":"2024-11-30T22:12:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"41bea037-6198-4d7f-9d50-911ff5b0377e","html_url":"https://github.com/llnl/parelagmc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/llnl/parelagmc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llnl%2Fparelagmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llnl%2Fparelagmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llnl%2Fparelagmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llnl%2Fparelagmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/llnl","download_url":"https://codeload.github.com/llnl/parelagmc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llnl%2Fparelagmc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34310801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monte-carlo","parallel","parallel-computing","simulation"],"created_at":"2024-11-11T21:33:33.629Z","updated_at":"2026-06-14T05:32:51.710Z","avatar_url":"https://github.com/llnl.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"/*\n  Copyright (c) 2018, Lawrence Livermore National Security, LLC. Produced at \n  Lawrence Livermore National Laboratory. LLNL-CODE-747639. All rights reserved.\n  Please see COPYRIGHT and LICENSE for details.                                                                            \n  This file is part of the ParELAGMC library. For more information and source \n  code availability see https://github.com/LLNL/parelagmc.                    \n                                                                             \n  ParELAGMC is free software; you can redistribute it and/or modify it        \n  under the terms of the GNU General Public License (as published by the      \n  Free Software Foundation) version 2, dated June 1991.  \n*/ \n###         Parallel Element Agglomeration Multilevel Monte Carlo Library\n\n                                 version 1.0\n```\n        ________              ____________________________________  ___________\n        ___  __ \\_____ __________  ____/__  /___    |_  ____/__   |/  /_  ____/\n        __  /_/ /  __ `/_  ___/_  __/  __  / __  /| |  / __ __  /|_/ /_  /\n        _  ____// /_/ /_  /   _  /___  _  /___  ___ / /_/ / _  /  / / / /___\n        /_/     \\__,_/ /_/    /_____/  /_____/_/  |_\\____/  /_/  /_/  \\____/\n\n```\n\n## Introduction\n\n`ParELAGMC` is a parallel distributed memory C++ library for multilevel \nMonte Carlo (MLMC) simulations with algebraically constructed coarse spaces, \nprimarily focusing on generating Gaussian random fields using a novel \nSPDE sampling technique.\n\n`ParELAGMC` enables multilevel variance reduction techniques in the context of\ngeneral unstructured meshes by using the specialized element-based\nagglomeration techniques implemented in [ParELAG](https://github.com/LLNL/parelag).\n\nThe nested hierarchies of algebraically coarse spaces produced by `ParELAG` are then\nused to discretize different realizations of the stochastic problem\nat different spatial resolution, thus allowing for optimal scaling of the\nmultilevel Monte Carlo Method.\n\n`ParELAGMC` implements different sampling techniques for spatially correlated\nrandom fields including the Karhunen–Loève expansion (KLE) for small scale problems\nand stochastic PDE (SPDE) samplers for large-scale applications.\nThe SPDE sampler provides samples from a Gaussian random field with a Matern \ncovariance function (equivalent to an exponential random field in 3D) \nand involves solving mixed finite element formulation of a \nstochastic reaction-diffusion equation with a random, white noise source \nfunction. Then the sampler is able to leverage existing scalable solution strategies, thus\nis a scalable alternative for sampling for large-scale simulations.\n\nAdditionally, the library provides functionality to compute the Bayesian \nposterior expectation of a quantity of interest. The posterior expectation can \nbe computed as a ratio of prior expectations, then approximated using Monte\nCarlo sampling methods. \n\nThe `ParELAGMC` library can support different type of deterministic problems.\nIn the examples, we present an application to subsurface flow simulation in\nthe mixed finite element setting.\n\nPlease see the following publications, and the references therein, \nfor an introduction to these methods:\n* [Paper 1 - SPDE sampler](https://doi.org/10.1137/16M1082688)\n* [Paper 2 - SPDE sampler with non-matching mesh embedding](https://doi.org/10.1002/nla.2146)\n\n## User Guide\n\n### Dependencies\n`ParELAGMC` requires a MPI C++ compiler, as well as the following \nexternal libraries:\n* [ParELAG library (v2.0)](https://github.com/LLNL/parelag)\n  generates the hierarchy of spatial discretizations \n  of general unstructured meshes. It builds on top of the \n  [MFEM](http://mfem.org) library for finite element methods, and the\n  [hypre](http://www.llnl.gov/CASC/hypre) preconditioner and sparse numerical\n  linear algebra library. `ParELAG` supports several solvers from the hypre \n  library which can be specified at runtime.\n\n* [Tina's Random Number Generator Library (TRNG)](https://numbercrunch.de/trng/)\n  is used for pseudo-random number generation which features dedicated support for\n  parallel, distributed environments.\n  * The library can be installed by the user **OR** the library will\n     be automatically downloaded and installed.\n\n`ParELAGMC` has optional dependencies that enable additional functionality:\n\n* [ParMoonolith](https://bitbucket.org/zulianp/par_moonolith.git) provides \n  volume transfer of discrete fields between arbitrarily distributed \n  unstructured finite element meshes.\n  * The library can be installed by the user **OR** the library will\n    be automatically downloaded and installed, if enabled.\n\n* [GLVis](http://glvis.org/) provides support for visualization of finite \n  element meshes, random field realizations, and \n  forward model problem solutions. \n\n### Building with CMake\n\n[CMake](https://cmake.org/) (version 3.1 or newer) is used to generate the \nbuild system for `ParELAGMC`.\n\nThe CMake system maintains an infrastructure to find and properly link\nthe required libraries when building the `ParELAGMC` library (see the\n\"Dependencies\" section for a complete list of the required and\noptional libraries).\n\n*PLEASE* DO NOT DO AN IN-SOURCE BUILD! It will pollute your source tree with \nvarious files generated and used by CMake. \nIt is best practice to create a build directory.    \n\nThe configuration step is performed by running \n\n```bash\n   mkdir \u003cbuild-dir\u003e ; cd \u003cbuild-dir\u003e                                \n   cmake \u003csource-dir\u003e [OPTIONS] ...\n```\nOptionally, a shell-script can be used to set the options and invoke CMake. Using a script\nprovides a convenient way to repeat the same configuration repeatedly. \nSome shell-script templates are located in `cmake/example_scripts` \nthat provide guidance on invoking CMake. These are provided merely as a \nsuggestion for different ways to build `ParELAGMC`. \n\nFor CMake to find the required libraries, set the environment variables \n  * `ParELAG_DIR=/path/to/parelag/build` Note: ParELAG *must* be configured using CMake. \n  \n  * `TRNG_DIR=/path/to/trng/install` If not found (or not specified), \n    the library will be automatically downloaded and installed.\n    `TRNG_INSTALL_PREFIX` can be used to set install location,\n    otherwise it is installed in `\u003cbuild-dir\u003e/external/trng4`. \n\nSome important flags/options are (defaults are in [brackets]):\n\n  * `ParELAGMC_ENABLE_ParMoonolith:BOOL={[ON],OFF}`\n\n    * This enables the library ParMoonolith which provides volume transfer\n    of discrete fields between arbitrarily distributed unstructured finite\n    element meshes. This is required for the SPDE sampler using non-matching\n    meshes to mitigate the artificially inflated variance.\n\n    * If enabled, the installed library is searched for in\n    `ParMoonolith_DIR`. If the library is not found, the library is automatically\n    downloaded and installed. The install location can be set with\n    `ParMoonolith_INSTALL_PREFIX`, other is `\u003cbuild-dir\u003e/external/par_moonolith`.\n\n  * `ParELAGMC_BUILD_EXAMPLES:BOOL={[ON],OFF}`: Build the examples directory.\n\n  * `ParELAGMC_BUILD_SPE10_EXAMPLES:BOOL={ON,[OFF]}`: Build the examples/SPE10 directory.\n\nAfter CMake configures and generates successfully, change to your\nbuild directory (the directory that is listed after \"Build files have\nbeen written to: \" at the bottom of the CMake output) and invoke the\nbuild system (i.e. call `make` or `ninja`, etc.) to build the library. \n\nThe build can be tested by running `ctest` in the build directory.\n\n[Doxygen](http://www.doxygen.org) documentation can be built by executing\n`make doc` in the build directory.\n\n### Using ParELAGMC\nThe intent of the library is to provide a modular methodology to specify\na Monte Carlo simulation by defining a forward model problem        \nsolver and a sampler strategy.  \n\nCurrently, the forward model problem is a mixed Darcy \nproblem (implemented in `DarcySolver`), whereas the sampler of a log-normal spatially correlated random \nfield (that is exp(s) where s is a Gaussian random field) \ncan be one of the following:\n\n* Truncated KLE with a Matern covariance function (equivalent to an exponential \n  random field in 3D) or an analytic exponential covariance.\n\n* SPDE sampler (3 different implementations)\n\n  * `PDESampler`: Solve SPDE on original mesh (the variance may be artificially \n    inflated along the boundary, especially near corners of spatial domain).  \n\n  * `EmbeddedPDESampler`: Solve SPDE on an enlarged, embedded mesh (that matches \n    the original mesh) then projects the sample to the original mesh.\n\n  * `L2ProjectionPDESampler`: Solve SPDE on an enlarged, structured \n    (non-matching) mesh then projects the sample to the original mesh. The two \n    meshes can be arbitrarily distributed among MPI processes. This is the \n    recommended sampling strategy. \n\nNote: For the SPDE sampler with mesh embedding, the boundary of the enlarged/embedded \nmesh should be at least a correlation length away from the boundary of the \noriginal mesh. \n\nThe linear solvers for the forward model problem and the saddle point \nlinear system for the SPDE sampler are specified at runtime from the software \nframework within ParELAG, using solvers and preconditioners from the HYPRE\npreconditioner and sparse numerical linear algebra library.\n\n#### Examples\nThe examples in the `examples/` directory build by default. Calling\none without arguments uses default values. \nTo specify parameter values, a XML parameter list is specified via command \nline (`--xml-file parameter_list.xml`).  \n\nSample parameters are found in `build_dir/examples/example_parameters.xml` and \nother parameters lists can be found in `src_dir/examples/example_parameterlists`. \n\nThe directory `/meshes` contains example finite element meshes, including\nembedded meshes with matching and non-matching interfaces useful for running \nexamples. Otherwise, a simple finite element mesh is built in the example.\n\nSome examples include:\n * `DarcyTest.cpp`: Solve a mixed Darcy problem with a deterministic permeability coefficient. \n\n * `DarcyTest_RandomInput.cpp`: Solve a mixed Darcy problem with a random \n    permeability coefficient generated with the SPDE sampler with non-matching mesh embedding.  \n \n * `EmbeddedPDESamplerTest.cpp`: Computes various statistics and realizations of the SPDE sampler with matching mesh embedding.\n\n * `KLSampler.cpp`: Samples a truncated KL Expansion of a random field, where underlying covariance function is either Matern or analytic exponential.\n\n * `MLMC.cpp`: Run a MLMC simulation for a mixed Darcy problem with random permeability realizations computed with either a truncated KLE using an analytic exponential or Matern covariance function, or the SPDE sampler (without mesh embedding).\n\n * `MLMC_ProjectionPDESampler.cpp`: Run a MLMC simulation for a mixed Darcy problem with random permeability realizations computed with the SPDE sampler with non-matching mesh embedding. \n \n * `PDESamplerTest.cpp`: Computes various statistics and realizations of the SPDE sampler without mesh embedding.\n\n * `ProjectionPDESamplerTest.cpp`: Computes various statistics and realizations of the SPDE sampler with non-matching mesh embedding. \n\n * `SLMC.cpp`: Single-level Monte Carlo simulation for a mixed Darcy problem with a random \npermeability coefficient samples using either a KL expansion (analytic exponential or Matern covariance function) or SPDE sampler with (non-matching) mesh embedding.\n\nAdditionally, the library provides functionality to compute the Bayesian \nposterior expectation of a quantity of interest. The posterior expectation can \nbe computed as a ratio of prior expectations using Bayes' rule, then \napproximated using Monte Carlo sampling methods. That is, \nE_posterior[Q] = E[Q \\Pi_{likelihood}]/E[\\Pi_likelihood]. \nAlso, the splitting estimator can be computed, that is,\nSplitting-E_posterior[Q] = E[(Q \\Pi_likelihood)/(\\Pi_likelihood)].\n\nThis methodology is examined in the following examples:\n \n * `RatioEstimator_MC.cpp`: Computes ratio estimates using single-level MC estimators for a fixed number of samples. \n \n * `RatioEstimator_MC_Manager.cpp`: Computes the ratio estimate (either splitting or standard) using single-level MC estimators where the number of samples is determined 'on the fly'. \n\n * `RatioEstimator_MLMC.cpp`: Computes ratio estimates using MLMC estimators for a fixed number of samples.\n\n * `RatioEstimator_MLMC_Manager.cpp`: Computes the ratio estimator (either splitting or standard) using MLMC estimators where the number of samples is determined 'on the fly'.\n\nExamples ending with `_Legacy` indicate that the forward model problem \nand sampler use a particular solver/preconditioner strategy to solve the \nresulting saddle point problems \nas specified in this [publication](https://doi.org/10.1137/16M1082688). \n\nAn optional directory of examples using the permeability data from the \n[SPE Comparative Solution Project Model 2](www.spe.org/web/csp/dataset/set02.htm) \nare found in `examples/SPE10`.\n\n### License \nCopyright information and licensing restrictions can be found in the file \n`COPYRIGHT`. The `ParELAGMC` library is licensed under the GPL v2.0, \nsee the file `LICENSE`. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fparelagmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllnl%2Fparelagmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fparelagmc/lists"}