From aa4e0e3e53eb024740c10b2656797c5b00f9b27a Mon Sep 17 00:00:00 2001 From: houpc Date: Thu, 30 Oct 2025 18:23:06 +0800 Subject: [PATCH 1/9] update readme and license --- README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++ license.md | 7 +++ 2 files changed, 148 insertions(+) create mode 100644 license.md diff --git a/README.md b/README.md index bccdd05..2e7618c 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,144 @@ [![alpha](https://img.shields.io/badge/docs-alpha-blue.svg)](https://numericaleft.github.io/MCintegration.py/) [![Build Status](https://github.com/numericalEFT/MCIntegration.py/workflows/CI/badge.svg)](https://github.com/numericalEFT/MCIntegration.py/actions) [![codecov](https://codecov.io/gh/numericalEFT/MCintegration.py/graph/badge.svg?token=851N2CNOTN)](https://codecov.io/gh/numericalEFT/MCintegration.py) +A Python library for Monte Carlo integration with support for multi-CPU and GPU computations. + +## Overview + +MCintegration is a specialized library designed for numerical integration using Monte Carlo methods. It provides efficient implementations of various integration algorithms with focus on applications in computational physics and effective field theories (EFT). + +The library offers: +- Multiple Monte Carlo integration algorithms +- Support for multi-CPU parallelization +- GPU acceleration capabilities +- Integration with PyTorch for tensor-based computations + +## Installation + +```bash +pip install mcintegration +``` + +Or install from source: + +```bash +python setup.py install +``` + +## Usage + +### Example 1: Unit Circle Integration + +This example demonstrates different Monte Carlo methods for integrating functions over [-1,1]×[-1,1]: + +```python +from MCintegration import MonteCarlo, MarkovChainMonteCarlo, Vegas +import torch + +# Define integrand function +def unit_circle(x, f): + r2 = x[:, 0]**2 + x[:, 1]**2 + f[:, 0] = (r2 <= 1).float() + return f.mean(dim=-1) + +# Set up integration parameters +dim = 2 +bounds = [(-1, 1)] * dim +n_eval = 6400000 +batch_size = 10000 +n_therm = 100 + +# Create integrator instances +mc = MonteCarlo(f=unit_circle, bounds=bounds, batch_size=batch_size) +mcmc = MarkovChainMonteCarlo(f=unit_circle, bounds=bounds, batch_size=batch_size, nburnin=n_therm) + +# Perform integration +result_mc = mc(n_eval) +result_mcmc = mcmc(n_eval) +``` + +### Example 2: Singular Function Integration + +This example shows integration of a function with a singularity at x=0: + +```python +# Integrate log(x)/sqrt(x) which has a singularity at x=0 +def singular_func(x, f): + f[:, 0] = torch.log(x[:, 0]) / torch.sqrt(x[:, 0]) + return f[:, 0] + +# Set up integration parameters +dim = 1 +bounds = [(0, 1)] +n_eval = 6400000 +batch_size = 10000 +n_therm = 100 + +# Use VEGAS algorithm which adapts to the singular structure +vegas_map = Vegas(dim, ninc=1000) +vegas_map.adaptive_training(batch_size, singular_func) + +# Create integrator instances using the adapted vegas map +vegas_mc = MonteCarlo(f=singular_func, bounds=bounds, batch_size=batch_size, maps=vegas_map) +vegas_mcmc = MarkovChainMonteCarlo(f=singular_func, bounds=bounds, batch_size=batch_size, nburnin=n_therm, maps=vegas_map) + +# Perform integration +result_vegas = vegas_mc(n_eval) +result_vegas_mcmc = vegas_mcmc(n_eval) +``` + +### Example 3: Multiple Sharp Peak Integrands in Higher Dimensions + +This example demonstrates integration of a sharp Gaussian peak and its moments in 4D space: + +```python +# Define a sharp peak and its moments integrands +# This represents a Gaussian peak centered at (0.5, 0.5, 0.5, 0.5) +def sharp_integrands(x, f): + f[:, 0] = torch.sum((x - 0.5) ** 2, dim=-1) # Distance from center + f[:, 0] *= -200 # Scale by width parameter + f[:, 0].exp_() # Exponentiate to create Gaussian + f[:, 1] = f[:, 0] * x[:, 0] # First moment + f[:, 2] = f[:, 0] * x[:, 0] ** 2 # Second moment + return f.mean(dim=-1) + +# Set up 4D integration with sharp peak +dim = 4 +bounds = [(0, 1)] * dim +n_eval = 6400000 +batch_size = 10000 +n_therm = 100 + +# Use VEGAS algorithm which adapts to the peak structure +vegas_map = Vegas(dim, ninc=1000) +vegas_map.adaptive_training(batch_size, sharp_integrands, f_dim=3) + +# Create integrator instances using the adapted vegas map +vegas_mc = MonteCarlo(f=sharp_integrands, f_dim=3, bounds=bounds, batch_size=batch_size, maps=vegas_map) +vegas_mcmc = MarkovChainMonteCarlo(f=sharp_integrands, f_dim=3, bounds=bounds, batch_size=batch_size, nburnin=n_therm, maps=vegas_map) + +# Perform integration +result_vegas = vegas_mc(n_eval) +result_vegas_mcmc = vegas_mcmc(n_eval) +``` + +## Features + +- **Base integration methods**: Core Monte Carlo algorithms in `MCintegration/base.py` +- **Integrator implementations**: Various MC integration strategies in `MCintegration/integrators.py` +- **Variable transformations**: Coordinate mapping utilities in `MCintegration/maps.py` +- **Utility functions**: Helper functions for numerical computations in `MCintegration/utils.py` +- **Multi-CPU support**: Parallel processing capabilities demonstrated in `MCintegration/mc_multicpu_test.py` +- **GPU acceleration**: CUDA-enabled functions through PyTorch in the examples directory + + +## Requirements + +- Python 3.7+ +- NumPy +- PyTorch +- gvar + +## Acknowledgements and Related Packages +The development of `MCIntegration.py` has been greatly inspired and influenced by `vegas` package. We would like to express our appreciation to the following: +- [vegas](https://github.com/gplepage/vegas) A Python package offering Monte Carlo estimations of multidimensional integrals, with notable improvements on the original Vegas algorithm. It's been a valuable reference for us. Learn more from the vegas [documentation](https://vegas.readthedocs.io/). **Reference: G. P. Lepage, J. Comput. Phys. 27, 192 (1978) and G. P. Lepage, J. Comput. Phys. 439, 110386 (2021) [arXiv:2009.05112](https://arxiv.org/abs/2009.05112)**. \ No newline at end of file diff --git a/license.md b/license.md new file mode 100644 index 0000000..b964bdf --- /dev/null +++ b/license.md @@ -0,0 +1,7 @@ +Copyright (c) 2025: Pengcheng Hou, Tao Wang, Caiyu Fan, and Kun Chen. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file From b512a03dbba7a4b77b1c72dc2b7c3790f22d4843 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8C=83=E6=89=8D=E6=B8=9D?= Date: Thu, 30 Oct 2025 21:31:38 +0800 Subject: [PATCH 2/9] fix codecov --- codecov.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/codecov.yml b/codecov.yml index 7cdebbd..24cf127 100644 --- a/codecov.yml +++ b/codecov.yml @@ -8,3 +8,5 @@ coverage: project: default: target: 95% +fixes: + - "MCintegration.py/MCintegration.py/::MCintegration.py/" From 58501f4c8d4615a41eeb16c4419c47bf85babb88 Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 10:46:32 +0800 Subject: [PATCH 3/9] update codecov.yml --- .github/workflows/CI.yml | 69 ++++++++++++++++++++++++++++++++++------ codecov.yml | 4 +-- 2 files changed, 61 insertions(+), 12 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 3827e33..78ef478 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -10,10 +10,11 @@ on: permissions: contents: write + pull-requests: write jobs: test: - name: Python ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }} + name: Python ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} runs-on: ${{ matrix.os }} strategy: fail-fast: false @@ -27,10 +28,10 @@ jobs: - x64 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: ${{ matrix.version }} @@ -40,8 +41,13 @@ jobs: pip install coverage pip install pytest pytest-cov pip install -r requirements.txt - - - name: Run tests + + - name: Configure Coverage Parallel Mode + run: | + echo '[run]' > .coveragerc + echo 'parallel = True' >> .coveragerc + + - name: Run tests (Parallel Data Collection) run: | export RANK=0 export LOCAL_RANK=0 @@ -49,20 +55,65 @@ jobs: export MASTER_ADDR=localhost export MASTER_PORT=12345 export PYTHONPATH=MCintegration - pytest --cov --cov-report=xml --ignore=examples + + # 使用 coverage run 运行 pytest 以确保多进程/多核测试数据的收集 + coverage run -m pytest --ignore=examples + + # 上传每个 Job 收集到的原始覆盖率数据文件 + - name: Upload coverage data artifact + uses: actions/upload-artifact@v3 + with: + name: coverage-data-${{ matrix.os }}-${{ matrix.arch }} + path: .coverage.* + + codecov: + name: Codecov Merge & Upload + runs-on: ubuntu-latest + needs: test + + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.12' + + - name: Install coverage (for combining) + run: pip install coverage + + # 下载所有 Job 收集到的覆盖率数据文件 + - name: Download all coverage data artifacts + uses: actions/download-artifact@v3 + with: + path: coverage-artifacts + # 合并所有数据文件并生成最终 XML 报告 + - name: Combine and Report + run: | + # 移动所有数据文件到根目录，以便 coverage combine 找到 + find coverage-artifacts -name ".coverage.*" -exec mv {} . \; + + # 合并所有 .coverage.* 文件，解决跨 Job 和多进程数据丢失问题 + coverage combine + + # 生成最终的 XML 报告 + coverage xml + + # 上传最终的合并报告 - name: Upload coverage to Codecov uses: codecov/codecov-action@v4 with: token: ${{ secrets.CODECOV_TOKEN }} - + files: ./coverage.xml + docs: name: Documentation runs-on: ubuntu-latest - needs: test + needs: codecov # 修改依赖，确保在 coverage 报告上传后才构建文档 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 # 升级 checkout action - name: Install dependencies run: | diff --git a/codecov.yml b/codecov.yml index 24cf127..ec6cea4 100644 --- a/codecov.yml +++ b/codecov.yml @@ -7,6 +7,4 @@ coverage: target: 80% project: default: - target: 95% -fixes: - - "MCintegration.py/MCintegration.py/::MCintegration.py/" + target: 95% \ No newline at end of file From 07fda8fed206a12d5a8bcae6e7337bdaad55f48b Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 10:49:28 +0800 Subject: [PATCH 4/9] update ci --- .github/workflows/CI.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 78ef478..9b789fd 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -28,10 +28,10 @@ jobs: - x64 steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v2 - name: Set up Python ${{ matrix.version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v2 with: python-version: ${{ matrix.version }} From 206ba89f175278e2ffa03a716712d77dd5d0a040 Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 10:54:26 +0800 Subject: [PATCH 5/9] upload ci --- .github/workflows/CI.yml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 9b789fd..f4d6188 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -24,14 +24,14 @@ jobs: os: - ubuntu-latest arch: - - x86 - x64 + - x86 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: ${{ matrix.version }} @@ -59,9 +59,9 @@ jobs: # 使用 coverage run 运行 pytest 以确保多进程/多核测试数据的收集 coverage run -m pytest --ignore=examples - # 上传每个 Job 收集到的原始覆盖率数据文件 + # Updated to v4 - name: Upload coverage data artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: coverage-data-${{ matrix.os }}-${{ matrix.arch }} path: .coverage.* @@ -72,7 +72,8 @@ jobs: needs: test steps: - - uses: actions/checkout@v3 + # Updated to v4 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 @@ -82,9 +83,9 @@ jobs: - name: Install coverage (for combining) run: pip install coverage - # 下载所有 Job 收集到的覆盖率数据文件 + # Updated to v4 - name: Download all coverage data artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: path: coverage-artifacts @@ -110,10 +111,10 @@ jobs: docs: name: Documentation runs-on: ubuntu-latest - needs: codecov # 修改依赖，确保在 coverage 报告上传后才构建文档 + needs: codecov steps: - - uses: actions/checkout@v3 # 升级 checkout action + - uses: actions/checkout@v4 - name: Install dependencies run: | From 325113cfef43081b06244d00c8c2e214da9445ac Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 10:59:39 +0800 Subject: [PATCH 6/9] update ci --- .github/workflows/CI.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index f4d6188..dbc3440 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -28,6 +28,7 @@ jobs: - x86 steps: + # Updated to v4 - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.version }} @@ -64,7 +65,10 @@ jobs: uses: actions/upload-artifact@v4 with: name: coverage-data-${{ matrix.os }}-${{ matrix.arch }} - path: .coverage.* + # 修复：同时上传 .coverage (单进程默认) 和 .coverage.* (多进程并行) 文件 + path: | + .coverage + .coverage.* codecov: name: Codecov Merge & Upload @@ -93,7 +97,8 @@ jobs: - name: Combine and Report run: | # 移动所有数据文件到根目录，以便 coverage combine 找到 - find coverage-artifacts -name ".coverage.*" -exec mv {} . \; + # find 命令现在可以安全运行，因为 download-artifact 应该已创建目录 + find coverage-artifacts -name ".coverage*" -exec mv {} . \; # 合并所有 .coverage.* 文件，解决跨 Job 和多进程数据丢失问题 coverage combine @@ -114,6 +119,7 @@ jobs: needs: codecov steps: + # Updated to v4 - uses: actions/checkout@v4 - name: Install dependencies From 32c1421cbd3aa3a63fac0a907f7536c27122ad37 Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 11:03:45 +0800 Subject: [PATCH 7/9] check path --- .github/workflows/CI.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index dbc3440..59be420 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -60,6 +60,10 @@ jobs: # 使用 coverage run 运行 pytest 以确保多进程/多核测试数据的收集 coverage run -m pytest --ignore=examples + # 【调试步骤】列出所有 .coverage 文件，检查文件是否被正确生成 + - name: Debug Coverage Files + run: ls -F .coverage* + # Updated to v4 - name: Upload coverage data artifact uses: actions/upload-artifact@v4 From db9df7ceb3422a949c42f36d7db172d0ca1f1ea9 Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 11:07:34 +0800 Subject: [PATCH 8/9] fix path --- .github/workflows/CI.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 59be420..3d831e2 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -69,10 +69,8 @@ jobs: uses: actions/upload-artifact@v4 with: name: coverage-data-${{ matrix.os }}-${{ matrix.arch }} - # 修复：同时上传 .coverage (单进程默认) 和 .coverage.* (多进程并行) 文件 - path: | - .coverage - .coverage.* + # 修复：简化路径，使用单个通配符匹配所有 .coverage 文件 + path: .coverage* codecov: name: Codecov Merge & Upload From 28c23166c879932d5fb7ff8c416e35e700e730fd Mon Sep 17 00:00:00 2001 From: fancaiyu Date: Fri, 31 Oct 2025 11:12:10 +0800 Subject: [PATCH 9/9] fix path --- .github/workflows/CI.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 3d831e2..5b633d8 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -69,8 +69,11 @@ jobs: uses: actions/upload-artifact@v4 with: name: coverage-data-${{ matrix.os }}-${{ matrix.arch }} - # 修复：简化路径，使用单个通配符匹配所有 .coverage 文件 - path: .coverage* + # 确保匹配所有以点开头的覆盖率文件和配置文件 + path: | + .coverage* + .coveragerc + # 移除了 match-dot-files: true，因为 actions/upload-artifact@v4 不支持此输入 codecov: name: Codecov Merge & Upload