Performs variational Monte Carlo (VMC) calcuations on lattice systems that are of interest to the authors of this code.
This package is made up of two distinct components:
vmc-coreis the heart of the Monte Carlo calculation, and is written in C++ for speed
pyvmcis a higher-level package that allows setting up, controlling, and analysis of calculations. It is written in python for ease-of-programming/use and flexibility, and communicates with the C++ code by using Cython.
premake4 is required for the build.
To compile and run (using e.g.
$ cd vmc-core $ premake4 --os=linux gmake && CXX=clang++ INCLUDES="-I/path/to/eigen3/include -I/path/to/boost/include" make
premake4 --help for a list of options. Note that it is possible
for premake to hook into a different build system instead of using
The code should compile on recent versions of
and possibly even
icc. We are only targeting compilers that
A sample build script, which compiles both
is located at
vmc-core API documentation
If doxygen is installed,
documentation can be generated by running:
$ cd vmc-core/ $ mkdir -p docs/ $ doxygen
Afterwards, HTML documentation will exist at vmc-core/docs/generated/html/index.html
If PDF output is desired, change directory to
vmc-core/docs/generated/latex/ and run
We use assertions liberally within
vmc-core. There are some
tests/assertions that slow the code significantly if enabled. To run
with these tests, compile with the flag
-DVMC_CAREFUL by running:
$ make config=careful
Be sure to pass all the appropriate environment variables, given above,
There are also some standalone unit tests, built upon the
googletest framework. To build and run these tests:
$ cd unittests/ $ premake4 --os=linux gmake && INCLUDES="-I/path/to/eigen3/include -I/path/to/boost/include" make && ./vmc-core-tests
Eventually we should also write a fuzz test for
Documentation on performing a simple calculation using
First make sure a recent
python is installed, along with
virtualenv. (The primary author of this code has been using
Python 3.3 lately, but the code should still work on Python 2.7.) The
clang++ for both compiling (
CC) and linking
CXX), and assumes certain (typical) directories for
pip command below compiles all the python dependencies given in
requirements.txt. Some of these have their own dependencies, which
must be installed.
$ virtualenv venv $ source venv/bin/activate $ pip install -r requirements.txt $ CC=clang++ CXX=clang++ python setup.py build_ext -I/usr/include/boost:/usr/include/eigen3 -Lvmc-core --inplace
Sometimes you must pass the option
--force to the
command, since changes to
vmc-core C++ header files are not
considered when determining which
.pyx files to recompile. In fact,
if one accelerates compilation using
ccache, then there is little penalty from
--force all the time, and the compilation is guaranteed to be
After having followed the instructions above, things will have compiled
but the operating system will not know where to look for the
vmc-core library when python needs to load it. It can either be
copied or symlinked to e.g.
/usr/local/lib, or the environment
variables can be set so that the library path is searched. For instance,
bash shell on Linux:
$ export LD_LIBRARY_PATH=/path/to/vmc/vmc-core
On Mac OS X, this variable is called
It is recommended to construct two scripts, one for building and one for executing python, to cut down on the effort needed to build and run things. Otherwise, the environment variables and commands can get out of hand.
py.test is used to perform unit tests of
$ PYTHONPATH=. py.test pyvmc
There are also Monte Carlo tests that use both
vmc-core to perform calculations and compare to previous (or known)
quantities. These are located in
pyvmc/mc_tests/ and can be executed
$ python pyvmc/mc_tests/__init__.py
Only wavefunctions whose (slave) particles obey Pauli exclusion are currently supported (i.e. fermions and hard-core bosons).
Only wavefunctions with a definite particle number are supported.
Also, only wavefunctions that have a definite S_z are supported. Otherwise, it is not entirely accurate to think of spin-up and spin-down particles as separate species (as the code does), since annihilation operators anticommute even if the spins of the two operators are different.
Another way of phrasing the above two requirements is that moves and operators must consist only of SiteHop's.
Ways in which things are currently in flux
At the moment the following things are broken:
- Renyi stuff uses only single particle moves, even on wavefunctions where that doesn't work well.
- Projected Fermi sea does not yet use multi-particle moves so does not work at half filling.
- Non-Bravais lattices have never been tested.
- Cylindrical boundary conditions have not yet been fully tested.
Research based on results of this code
- “Non-Fermi-liquid d-wave metal phase of strongly interacting electrons,” Hong-Chen Jiang, Matthew S. Block, Ryan V. Mishmash, James R. Garrison, D. N. Sheng, Olexei I. Motrunich and Matthew P. A. Fisher, Nature 493, 39-44 (2013) [arXiv:1207.6608]. (used for Renyi entropy calculations)
- “Theory of a competitive spin liquid state for κ-(BEDT-TTF)2Cu2(CN)3 and EtMe3Sb[Pd(dmit)2]2,” Ryan V. Mishmash, James R. Garrison, Samuel Bieri and Cenke Xu [arXiv:1307.0829]. (used for roughly half of the VMC calculations)