Skip to content

Commit aa4e0e3

Browse files
houpchoupc
committed
update readme and license
1 parent ef95625 commit aa4e0e3

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎README.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,144 @@
22
[![alpha](https://img.shields.io/badge/docs-alpha-blue.svg)](https://numericaleft.github.io/MCintegration.py/)
33
[![Build Status](https://github.com/numericalEFT/MCIntegration.py/workflows/CI/badge.svg)](https://github.com/numericalEFT/MCIntegration.py/actions)
44
[![codecov](https://codecov.io/gh/numericalEFT/MCintegration.py/graph/badge.svg?token=851N2CNOTN)](https://codecov.io/gh/numericalEFT/MCintegration.py)
5+
A Python library for Monte Carlo integration with support for multi-CPU and GPU computations.
6+
7+
## Overview
8+
9+
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).
10+
11+
The library offers:
12+
- Multiple Monte Carlo integration algorithms
13+
- Support for multi-CPU parallelization
14+
- GPU acceleration capabilities
15+
- Integration with PyTorch for tensor-based computations
16+
17+
## Installation
18+
19+
```bash
20+
pip install mcintegration
21+
```
22+
23+
Or install from source:
24+
25+
```bash
26+
python setup.py install
27+
```
28+
29+
## Usage
30+
31+
### Example 1: Unit Circle Integration
32+
33+
This example demonstrates different Monte Carlo methods for integrating functions over [-1,1]×[-1,1]:
34+
35+
```python
36+
from MCintegration import MonteCarlo, MarkovChainMonteCarlo, Vegas
37+
import torch
38+
39+
# Define integrand function
40+
def unit_circle(x, f):
41+
r2 = x[:, 0]**2 + x[:, 1]**2
42+
f[:, 0] = (r2 <= 1).float()
43+
return f.mean(dim=-1)
44+
45+
# Set up integration parameters
46+
dim = 2
47+
bounds = [(-1, 1)] * dim
48+
n_eval = 6400000
49+
batch_size = 10000
50+
n_therm = 100
51+
52+
# Create integrator instances
53+
mc = MonteCarlo(f=unit_circle, bounds=bounds, batch_size=batch_size)
54+
mcmc = MarkovChainMonteCarlo(f=unit_circle, bounds=bounds, batch_size=batch_size, nburnin=n_therm)
55+
56+
# Perform integration
57+
result_mc = mc(n_eval)
58+
result_mcmc = mcmc(n_eval)
59+
```
60+
61+
### Example 2: Singular Function Integration
62+
63+
This example shows integration of a function with a singularity at x=0:
64+
65+
```python
66+
# Integrate log(x)/sqrt(x) which has a singularity at x=0
67+
def singular_func(x, f):
68+
f[:, 0] = torch.log(x[:, 0]) / torch.sqrt(x[:, 0])
69+
return f[:, 0]
70+
71+
# Set up integration parameters
72+
dim = 1
73+
bounds = [(0, 1)]
74+
n_eval = 6400000
75+
batch_size = 10000
76+
n_therm = 100
77+
78+
# Use VEGAS algorithm which adapts to the singular structure
79+
vegas_map = Vegas(dim, ninc=1000)
80+
vegas_map.adaptive_training(batch_size, singular_func)
81+
82+
# Create integrator instances using the adapted vegas map
83+
vegas_mc = MonteCarlo(f=singular_func, bounds=bounds, batch_size=batch_size, maps=vegas_map)
84+
vegas_mcmc = MarkovChainMonteCarlo(f=singular_func, bounds=bounds, batch_size=batch_size, nburnin=n_therm, maps=vegas_map)
85+
86+
# Perform integration
87+
result_vegas = vegas_mc(n_eval)
88+
result_vegas_mcmc = vegas_mcmc(n_eval)
89+
```
90+
91+
### Example 3: Multiple Sharp Peak Integrands in Higher Dimensions
92+
93+
This example demonstrates integration of a sharp Gaussian peak and its moments in 4D space:
94+
95+
```python
96+
# Define a sharp peak and its moments integrands
97+
# This represents a Gaussian peak centered at (0.5, 0.5, 0.5, 0.5)
98+
def sharp_integrands(x, f):
99+
f[:, 0] = torch.sum((x - 0.5) ** 2, dim=-1) # Distance from center
100+
f[:, 0] *= -200 # Scale by width parameter
101+
f[:, 0].exp_() # Exponentiate to create Gaussian
102+
f[:, 1] = f[:, 0] * x[:, 0] # First moment
103+
f[:, 2] = f[:, 0] * x[:, 0] ** 2 # Second moment
104+
return f.mean(dim=-1)
105+
106+
# Set up 4D integration with sharp peak
107+
dim = 4
108+
bounds = [(0, 1)] * dim
109+
n_eval = 6400000
110+
batch_size = 10000
111+
n_therm = 100
112+
113+
# Use VEGAS algorithm which adapts to the peak structure
114+
vegas_map = Vegas(dim, ninc=1000)
115+
vegas_map.adaptive_training(batch_size, sharp_integrands, f_dim=3)
116+
117+
# Create integrator instances using the adapted vegas map
118+
vegas_mc = MonteCarlo(f=sharp_integrands, f_dim=3, bounds=bounds, batch_size=batch_size, maps=vegas_map)
119+
vegas_mcmc = MarkovChainMonteCarlo(f=sharp_integrands, f_dim=3, bounds=bounds, batch_size=batch_size, nburnin=n_therm, maps=vegas_map)
120+
121+
# Perform integration
122+
result_vegas = vegas_mc(n_eval)
123+
result_vegas_mcmc = vegas_mcmc(n_eval)
124+
```
125+
126+
## Features
127+
128+
- **Base integration methods**: Core Monte Carlo algorithms in `MCintegration/base.py`
129+
- **Integrator implementations**: Various MC integration strategies in `MCintegration/integrators.py`
130+
- **Variable transformations**: Coordinate mapping utilities in `MCintegration/maps.py`
131+
- **Utility functions**: Helper functions for numerical computations in `MCintegration/utils.py`
132+
- **Multi-CPU support**: Parallel processing capabilities demonstrated in `MCintegration/mc_multicpu_test.py`
133+
- **GPU acceleration**: CUDA-enabled functions through PyTorch in the examples directory
134+
135+
136+
## Requirements
137+
138+
- Python 3.7+
139+
- NumPy
140+
- PyTorch
141+
- gvar
142+
143+
## Acknowledgements and Related Packages
144+
The development of `MCIntegration.py` has been greatly inspired and influenced by `vegas` package. We would like to express our appreciation to the following:
145+
- [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)**.

‎license.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright (c) 2025: Pengcheng Hou, Tao Wang, Caiyu Fan, and Kun Chen.
2+
3+
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:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
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.

0 commit comments

Comments
 (0)