Package and Installation

PyGFMC is a pure-Python package; there is nothing to compile. It needs Python 3.11 or newer.

Installation from PyPI

PyGFMC is available on PyPI:

pip install pygfmc               # GFMC only
pip install "pygfmc[netket]"     # + training guides with NetKet

Installation from source

To modify the code or run the tests, install from source. The source is on GitHub at https://github.com/robin-schaefer/PyGFMC.

git clone https://github.com/robin-schaefer/PyGFMC.git
cd PyGFMC
pip install -e "./codes"             # GFMC only
pip install -e "./codes[netket]"     # + training guides with NetKet

For GPU runs, install the appropriate CUDA build of JAX first: JAX installation guide.

The editable install -e makes changes to the source code take effect without reinstalling. Alternatively, without installing, codes/ can be added to your PYTHONPATH.

Tests

To check the installation:

python -c "import pygfmc; print(pygfmc.__version__)"

To run the tests, install the test extra (pytest) and run pytest from the tests/ folder:

pip install -e "./codes[test]"
cd tests
pytest core -q                       # core suite (about 50 minutes on one CPU)
RUN_GFMC_BENCH=1 pytest benchmark -q # benchmarks (about 140 minutes)

One section in the appendix of the Paper is dedicated to the tests.

Package setup

PyGFMC has four subpackages:

  • pygfmc.walkers: the walker population, its initializers and reconfiguration,

  • pygfmc.engine: the GFMC engine (propagation, estimators, HDF5 storage). These functions are also available directly from pygfmc,

  • pygfmc.hamiltonian: Hamiltonians, lattices and observables,

  • pygfmc.wavefunction: guiding wavefunctions and their training.

The module pygfmc.protocols defines the interfaces for a Hamiltonian, an observable or a guide (Operator, DiagonalOperator, Guide), which is useful when implementing your own classes.

from pygfmc.walkers import Walker, prepare_walkers_random, prepare_walkers_sz
from pygfmc.engine import run, statistics, evaluate_observables, write_to_HDF5, run_from_HDF5
from pygfmc.hamiltonian import SpinHalf, chain, exact_diagonalization
from pygfmc.wavefunction import JastrowSpinHalf, ClusterCPS, ClusterMLP, train_with_netket

Dependencies

The core dependencies are installed automatically:

  • JAX (with the matching CUDA build for GPU runs)

  • NumPy and SciPy

  • h5py for walker checkpoints and results

pygfmc[netket] requires additional dependencies (NetKet, optax and Flax), which are needed only to train guides with NetKet within PyGFMC.

Contact

Please reach out for feedback, tips and bugs: robin_schaefer@fas.harvard.edu

Bug reports and questions are also welcome as GitHub issues.