Skip to content

README.md

Latest commit

 

History

History
173 lines (122 loc) · 6.3 KB

README.md

File metadata and controls

173 lines (122 loc) · 6.3 KB

QMC.jl: Quasi-Monte Carlo Community Software in Julia

CI CI Full Docs codecov License

A Julia port of QMCPy — quasi-Monte Carlo point generators, measure transforms, and adaptive stopping criteria for high-dimensional numerical integration.

Quick Start

using QMC

dd = Lattice(3; randomize=true, seed=7)
tm = Gaussian(dd; covariance=0.5)
f  = Keister(tm)
sc = CubQMCLatticeG(f; abs_tol=1e-3)

result = integrate(sc)
println("Estimate: $(result.solution)")   # ≈ 2.168
println("Exact:    $(keister_exact(3))")

Components

QMC.jl provides four core building blocks, plus related kernel types:

Component Types
Discrete Distribution IIDStdUniform, Lattice, DigitalNetB2, Halton, Kronecker, DigitalNetAnyBases, Faure
True Measure Uniform, Gaussian, BrownianMotion, Lebesgue, GeometricBrownianMotion, StudentT, Triangular, Kumaraswamy, JohnsonsSU, BernoulliCont, AcceptanceRejection, AcceptanceRejectionReal, DistributionsWrapper, MaternGP, UniformTriangle, ZeroInflatedExpUniform
Integrand Keister, Genz, AsianOption, FinancialOption, FinancialOptionML, BoxIntegral, Linear0, Sin1D, Ishigami, Hartmann6D, Multimodal2D, FourBranch2D, SensitivityIndices, BayesianLRCoeffs, UMBridgeWrapper, CustomFun
Stopping Criterion CubMCCLT, CubMCCLTVec, CubMCG, CubQMCLatticeG, CubQMCNetG, CubQMCNetGRep, CubQMCBayesLatticeG, CubQMCBayesNetG, CubQMCRepStudentT, CubMLMC, CubMLMCCont, CubMLQMC, CubMLQMCCont, PFGPCI
Kernel KernelShiftInvar, KernelDigShiftInvar, KernelMatern12, KernelMatern32, KernelMatern52, KernelGaussian, KernelRationalQuadratic, KernelSquaredExponential, KernelMultiTask, SumKernel, ProductKernel

Additional utilities include periodization transforms, iteration diagnostics (IterationLog), resume/checkpoint support, Walsh-Hadamard and BRO-FFT transforms, and a LatNetBuilder linker.

Advanced status notes: PFGPCI is currently exported as a parity placeholder, but integrate(::PFGPCI) intentionally errors until a Julia GP backend is implemented. Likewise, gpu_fwht! is currently a CPU-fallback stub rather than a real GPU acceleration path.

Installation

Prerequisites

Tool Version Notes
Julia ≥ 1.10 Language runtime
Python ≥ 3.9 Required for QMCToolsCL-backed generators

Steps

# Clone the repository
git clone https://github.com/QMCSoftware/QMC.jl.git
cd QMC.jl

# Install Julia dependencies
julia --project=. -e 'using Pkg; Pkg.instantiate()'

# Install QMCToolsCL (for Lattice, DigitalNetB2, Halton)
pip install qmctoolscl

# Run tests
julia --project=. -e 'using Pkg; Pkg.test()'

If Julia should use a specific Python interpreter:

ENV["QMC_PYTHON"] = "/path/to/python"

Optional: Jupyter Notebook Kernel

julia -e 'using Pkg; Pkg.add("IJulia")'
julia -e 'using IJulia; IJulia.installkernel("QMC", "--project=$(pwd())")'

Demos

26 Jupyter notebooks in demos/ cover topics from basic sampling to multilevel QMC, Bayesian optimization, sensitivity analysis, and UMBridge integration. See demos/README.md for the full list.

# Run all demos
julia --project=. test/run_notebooks.jl

# Run a single demo
julia --project=. test/run_notebooks.jl quickstart

# Launch in Jupyter
julia -e 'using IJulia; notebook(dir="demos")'

Benchmarks

Run the benchmark suite:

make bench
# or
julia benchmark/runbenchmarks.jl

This benchmarks sampling, transforms, integrand evaluation, and end-to-end integration across all DD types. Results are saved under benchmark/results/. See benchmark/README.md for the full workflow, comparison scripts, and the Julia-vs-QMCPy accuracy sidecars.

Repository Layout

Most top-level and source subdirectories now include a local README.md describing their purpose and the files they contain. Useful starting points:

Documentation

Full API documentation: qmcsoftware.github.io/QMC.jl

In the Julia REPL:

using QMC
?Lattice               # help mode
@doc CubQMCBayesNetG   # docstring

Testing

# Unit tests
julia --project=. -e 'using Pkg; Pkg.test()'

# Unit tests with coverage instrumentation
julia --project=. -e 'using Pkg; Pkg.test(coverage=true)'
# or
make coverage

# Demo notebooks
julia --project=. test/run_notebooks.jl

# Build documentation locally
julia --project=docs docs/make.jl

CI uploads LCOV coverage reports to Codecov and stores the generated lcov.info as a workflow artifact. See test/README.md and CI/CD Testing for details.

Citation

@misc{qmcjl2026,
  author = {Sou-Cheng T. Choi and Fred J. Hickernell and Aleksei G. Sorokin and contributors},
  title  = {{QMC.jl}: Quasi-Monte Carlo Community Software in Julia},
  year   = {2026},
  url    = {https://github.com/QMCSoftware/QMC.jl}
}

Editorial Note

Some repository content was partially produced with the help of AI tools (e.g., Claude and GPT) and was reviewed by the authors and contributors.

License

Apache 2.0 — see LICENSE for details.