vmc

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-core is the heart of the Monte Carlo calculation, and is written in C++ for speed
• pyvmc is 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.

Compiling vmc-core

premake4 is required for the build.

Requires boost >= 1.55 (headers only) and eigen3.

To compile and run (using e.g. clang++):

$ cd vmc-core
$ premake4 --os=linux gmake && CXX=clang++ INCLUDES="-I/path/to/eigen3/include -I/path/to/boost/include" make

Run premake4 --help for a list of options. Note that it is possible for premake to hook into a different build system instead of using make.

The code should compile on recent versions of g++, clang++, and possibly even icc. We are only targeting compilers that support C++11.

A sample build script, which compiles both vmc-core and pyvmc, is located at ./do-build.example.

vmc-core API documentation

If doxygen is installed, vmc-core API 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 make.

vmc-core tests

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, to make.

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 CeperleyMatrix.

pyvmc

Documentation on performing a simple calculation using pyvmc is coming soon.

Compiling pyvmc

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 following uses clang++ for both compiling (CC) and linking (CXX), and assumes certain (typical) directories for boost and eigen.

The 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 build_ext 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 using --force all the time, and the compilation is guaranteed to be correct.

LD_LIBRARY_PATH

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, in the bash shell on Linux:

$ export LD_LIBRARY_PATH=/path/to/vmc/vmc-core

On Mac OS X, this variable is called DYLD_LIBRARY_PATH instead.

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.

pyvmc tests

py.test is used to perform unit tests of pyvmc:

$ PYTHONPATH=. py.test pyvmc

There are also Monte Carlo tests that use both pyvmc and vmc-core to perform calculations and compare to previous (or known) quantities. These are located in pyvmc/mc_tests/ and can be executed by running:

$ python pyvmc/mc_tests/__init__.py

Caveats

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)₂Cu₂(CN)₃ and EtMe₃Sb[Pd(dmit)₂]₂,” Ryan V. Mishmash, James R. Garrison, Samuel Bieri and Cenke Xu [arXiv:1307.0829]. (used for roughly half of the VMC calculations)