QMC Lib

A Python library for Monte Carlo and Quasi-Monte Carlo numerical integration.

---

Overview

qmc_lib is a Python library for experimenting with Monte Carlo and Quasi-Monte Carlo methods for numerical integration.

The goal of the library is to provide simple, readable, and explicit implementations of several sampling methods. It is designed to make it easy to generate point sets, approximate integrals, compare sampling methods, visualize their behavior, and run basic benchmarks.

The library is mainly intended for educational and experimental purposes. It focuses on clarity and usability, while still providing practical tools for numerical integration on the unit cube.

---

Features

The library currently provides the following sampling methods:

• Uniform Monte Carlo sampling
• Latin Hypercube Sampling
• Halton sequence
• Sobol sequence
• Lattice rules
• Kronecker sequence

It also includes tools for:

• numerical integration on the unit cube;
• statistical estimation;
• confidence intervals for random methods;
• visualization of point sets;
• comparison of approximation errors;
• benchmarking against existing QMC libraries.

---

Installation

You can install qmc_lib directly from GitHub:

pip install git+https://github.com/Samuel-Vangu/qmc-lib

To check that the installation works:

from qmc_lib.sampling.Sobol import SobolSampler

sampler = SobolSampler(dimension=2, n_samples=1024, seed=0)
samples = sampler.generate()

print(samples.shape)

Expected output:

(1024, 2)

For development, clone the repository and install it in editable mode:

git clone https://github.com/Samuel-Vangu/qmc-lib
cd qmc-lib
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install -r requirements.txt
pip install -e .

Optional benchmark and development tools can be installed with:

pip install ".[dev,benchmark]"

Quick Start

The library follows a simple workflow:

1. choose a sampling method;
2. generate points in the unit cube;
3. pass the points to the integrator;
4. compute the approximation.

The following example approximates an integral over $[0,1]^d$ using a Sobol point set.

import numpy as np

from qmc_lib.sampling.Sobol import SobolSampler
from qmc_lib.integration.Integrate import Integrator

# Function to integrate on [0,1]^d
def f(x):
    return np.prod(1.0 / (1.0 + x))

dimension = 4
n_samples = 4096
seed = 0

# Generate Sobol points
samples = SobolSampler(
    dimension=dimension,
    n_samples=n_samples,
    seed=seed,
).generate()

# Approximate the integral
estimate = Integrator(
    f=f,
    samples=samples,
).compute()

print(f"Estimate: {estimate}")

For this function,

$$ f(x)=\prod_{i=1}^d \frac{1}{1+x_i}, $$

the exact value of the integral is

$$ \int_{[0,1]^d} f(x),dx = (\log 2)^d. $$

Therefore, the exact value can be computed with:

exact_value = np.log(2.0) ** dimension
absolute_error = abs(estimate - exact_value)

print(f"Exact value: {exact_value}")
print(f"Absolute error: {absolute_error}")

---

Using Other Sampling Methods

All sampling methods in the library follow the same general interface:

sampler = SamplerClass(
    dimension=dimension,
    n_samples=n_samples,
    seed=seed,
)

samples = sampler.generate()

This means that once you know how to use one sampler, you can use the others in almost the same way.

For example, you can replace SobolSampler with another sampler:

from qmc_lib.sampling.Halton import HaltonSampler
from qmc_lib.sampling.LatinHypercube import LatinHypercubeSampler
from qmc_lib.sampling.LatticeRule import LatticeSampler
from qmc_lib.sampling.Kronecker import KroneckerSampler
from qmc_lib.sampling.UniformSampler import UniformSampler

Example with Halton:

samples = HaltonSampler(
    dimension=dimension,
    n_samples=n_samples,
    seed=seed,
).generate()

estimate = Integrator(
    f=f,
    samples=samples,
).compute()

Example with Uniform Monte Carlo:

samples = UniformSampler(
    dimension=dimension,
    n_samples=n_samples,
    seed=seed,
).generate()

estimate = Integrator(
    f=f,
    samples=samples,
).compute()

Example with Latin Hypercube Sampling:

samples = LatinHypercubeSampler(
    dimension=dimension,
    n_samples=n_samples,
    seed=seed,
).generate()

estimate = Integrator(
    f=f,
    samples=samples,
).compute()

This common structure makes it easy to compare different methods on the same integration problem.

---

Visualization

The library also provides visualization tools to compare how different sampling methods fill the unit square.

from qmc_lib.visualization import Visualization

Visualization.compare_point_sets_2d(
    samples_dict={
        "Sobol": sobol_samples,
        "Halton": halton_samples,
        "Uniform": uniform_samples,
    }
)

These visualizations help illustrate the difference between purely random point sets and more structured low-discrepancy point sets.

Example visualization of different sampling methods in two dimensions.

---

Example: Expected Loss Estimation

One of the main examples of the library is the estimation of the expected loss of a regression model.

The goal is to approximate a quantity of the form

$$ \mathbb{E} \left[ \left( y_{\mathrm{model}}(X)-Y \right)^2 \right]. $$

After transforming Gaussian random variables into uniform variables on the unit cube, the problem becomes an integral over $[0,1]^4$. This allows all sampling methods implemented in the library to be applied in the same framework.

The corresponding notebook can be found in:

examples/notebooks/qmc_expected_loss_example.ipynb

---

Benchmark

A benchmark was performed to compare qmc_lib with QMCPy, an existing Python library for Monte Carlo and Quasi-Monte Carlo integration.

The comparison focuses on two aspects:

1. Accuracy We compare the absolute error of the estimators against an exact reference value.

2. Point generation time We benchmark only the time required to generate the point sets. The evaluation time of the integrand is not the main focus here, since both libraries use the same function evaluation step. The timing benchmark is performed with pyperf.

The methods compared with QMCPy are the ones available in both libraries:

• Uniform sampling
• Sobol sequence
• Halton sequence
• Lattice rules

Accuracy comparison between qmc_lib and QMCPy.

Mean point generation time as a function of the number of samples.

Mean point generation time as a function of the dimension.

The benchmark shows that qmc_lib gives coherent numerical approximations and that its estimators converge toward the reference value. QMCPy often achieves better accuracy for some QMC methods, which is expected from a mature and optimized library.

On the other hand, qmc_lib is faster for basic point generation in this benchmark. This reflects its simpler and more direct implementation style. Overall, the benchmark highlights a clear trade-off: QMCPy provides more advanced QMC tools, while qmc_lib remains lightweight, readable, and useful for educational and experimental purposes.

Project Context

This library was developed as part of my Stage d'Excellence at Université Grenoble Alpes.

The project was carried out in the DAO team of the LJK lab — Data, Learning and Optimization — under the supervision of Quoc-Tung Le.

The main objective of the internship was to study Monte Carlo and Quasi-Monte Carlo methods for numerical integration, both from a theoretical and computational point of view.

---

Repository Structure

qmc_lib/
    sampling/          # Sampling methods
    integration/       # Numerical integration tools
    visualization/     # Visualization utilities

examples/
    notebooks/         # Example notebooks
benchmarks/        # Benchmark scripts and results

---

License

This project is currently intended for educational and research purposes.

---

Author

Samuel Vangu

Université Grenoble Alpes

DAO team, LJK lab — Data, Learning and Optimization