Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/garrison/vmc


https://github.com/garrison/vmc

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

README 

        
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 :math:`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)



.. |κ-(BEDT-TTF)2Cu2(CN)3| replace:: κ-(BEDT-TTF)\ :sub:`2`\ Cu\ :sub:`2`\ (CN)\ :sub:`3`

.. |EtMe3Sb[Pd(dmit)2]2| replace:: EtMe\ :sub:`3`\ Sb[Pd(dmit)\ :sub:`2`\ ]\ :sub:`2`