update README

Modify gf_struct to be in line with triqs/3.1.x

.clang-tidy

@@ -0,0 +1,2 @@
+Checks: '-*,modernize-*,cppcoreguidelines-*,-modernize-use-trailing-return-type'
+HeaderFilterRegex: 'triqs_dft_tools'

.dockerignore

@@ -1,2 +1,5 @@
+.travis.yml
 Dockerfile
 Jenkinsfile
+.git/objects/pack
+build*

.github/ISSUE_TEMPLATE/bug.md

@@ -32,7 +32,7 @@ Please provide the application version that you used.
 
 You can get this information from copy and pasting the output of
 ```bash
-python -c "from app4triqs.version import *; show_version(); show_git_hash();"
+python -c "from triqs_dft_tools.version import *; show_version(); show_git_hash();"
 ```
 from the command line. Also, please include the OS you are running and its version.
 

.github/workflows/build.yml

@@ -0,0 +1,98 @@
+name: build
+
+on:
+  push:
+    branches: [ unstable ]
+  pull_request:
+    branches: [ unstable ]
+
+jobs:
+  build:
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-20.04, cc: gcc-10, cxx: g++-10}
+          - {os: ubuntu-20.04, cc: clang-13, cxx: clang++-13}
+          - {os: macos-11, cc: gcc-11, cxx: g++-11}
+          - {os: macos-11, cc: /usr/local/opt/llvm/bin/clang, cxx: /usr/local/opt/llvm/bin/clang++}
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install ubuntu dependencies
+      if: matrix.os == 'ubuntu-20.04'
+      run: >
+        sudo apt-get update &&
+        sudo apt-get install lsb-release wget software-properties-common &&
+        wget -O /tmp/llvm.sh https://apt.llvm.org/llvm.sh && sudo chmod +x /tmp/llvm.sh && sudo /tmp/llvm.sh 13 &&
+        sudo apt-get install
+        clang-13
+        g++-10
+        gfortran-10
+        hdf5-tools
+        libblas-dev
+        libboost-dev
+        libclang-13-dev
+        libc++-13-dev
+        libc++abi-13-dev
+        libomp-13-dev
+        libfftw3-dev
+        libgfortran5
+        libgmp-dev
+        libhdf5-dev
+        liblapack-dev
+        libopenmpi-dev
+        openmpi-bin
+        openmpi-common
+        openmpi-doc
+        python3-clang-13
+        python3-dev
+        python3-mako
+        python3-matplotlib
+        python3-mpi4py
+        python3-numpy
+        python3-pip
+        python3-scipy
+        python3-sphinx
+        python3-nbsphinx
+
+    - name: Install homebrew dependencies
+      if: matrix.os == 'macos-11'
+      run: |
+        brew install gcc@11 llvm boost fftw hdf5 open-mpi openblas
+        pip3 install mako numpy scipy mpi4py
+        pip3 install -r requirements.txt
+
+    - name: Build & Install TRIQS
+      env:
+        CC: ${{ matrix.cc }}
+        CXX: ${{ matrix.cxx }}
+      run: |
+        git clone https://github.com/TRIQS/triqs --branch unstable
+        mkdir triqs/build && cd triqs/build
+        cmake .. -DBuild_Tests=OFF -DCMAKE_INSTALL_PREFIX=$HOME/install
+        make -j1 install VERBOSE=1
+        cd ../
+
+    - name: Build dft_tools
+      env:
+        CC: ${{ matrix.cc }}
+        CXX: ${{ matrix.cxx }}
+        FC: gfortran-10
+        LIBRARY_PATH: /usr/local/opt/llvm/lib
+      run: |
+        source $HOME/install/share/triqs/triqsvars.sh
+        mkdir build && cd build && cmake ..
+        make -j2 || make -j1 VERBOSE=1
+
+    - name: Test app4triqs
+      env:
+        DYLD_FALLBACK_LIBRARY_PATH: /usr/local/opt/llvm/lib
+      run: |
+        source $HOME/install/share/triqs/triqsvars.sh
+        cd build
+        ctest -j2 --output-on-failure

.gitignore

@@ -0,0 +1,2 @@
+compile_commands.json
+doc/cpp2rst_generated

.travis.yml

@@ -1,47 +0,0 @@
-
-language: cpp
-sudo: required
-dist: trusty
-
-compiler:
-  - gcc
-    #  - clang
-
-before_install:
-  - sudo add-apt-repository 'deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-5.0 main' -y
-  - wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add -
-  - sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
-  - sudo apt-get update
-  - sudo apt-get install -y --allow-unauthenticated g++-7 clang-5.0
-  - export LIBRARY_PATH=/usr/lib/llvm-5.0/lib:$LIBRARY_PATH
-  - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 --slave /usr/bin/g++ g++ /usr/bin/g++-7
-  - sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-5.0 60 --slave /usr/bin/clang++ clang++ /usr/bin/clang++-5.0
-  - sudo apt-get install -y --allow-unauthenticated libboost-all-dev cmake git libgfortran3 gfortran openmpi-bin openmpi-common openmpi-doc libopenmpi-dev libblas-dev liblapack-dev libfftw3-dev libgmp-dev hdf5-tools libhdf5-serial-dev python-h5py python-dev python-numpy python-scipy python-jinja2 python-virtualenv python-matplotlib python-tornado python-zmq python-mpi4py python-mako clang-format-5.0 libclang-5.0-dev python-clang-5.0 python-sphinx libjs-mathjax valgrind libnfft3-dev
-
-install: true
-
-script:
-  # ===== Set up Cpp2Py
-  - git clone https://github.com/triqs/cpp2py
-  - mkdir cpp2py/build && cd cpp2py/build
-  - git checkout master
-  - cmake .. -DCMAKE_CXX_COMPILER=/usr/bin/${CXX} -DPYTHON_INTERPRETER=/usr/bin/python -DCMAKE_INSTALL_PREFIX=$TRAVIS_BUILD_DIR/root_install
-  - make -j8 install
-  - cd $TRAVIS_BUILD_DIR
-  - source root_install/share/cpp2pyvars.sh
-  # ===== Set up TRIQS
-  - git clone https://github.com/TRIQS/triqs --branch $TRAVIS_BRANCH
-  - mkdir triqs/build && cd triqs/build
-  - cmake .. -DCMAKE_CXX_COMPILER=/usr/bin/${CXX} -DBuild_Tests=OFF -DCMAKE_INSTALL_PREFIX=$TRAVIS_BUILD_DIR/root_install -DCMAKE_BUILD_TYPE=Debug
-  - make -j8 install
-  - cd $TRAVIS_BUILD_DIR
-  - source root_install/share/triqsvars.sh
-  # ===== Set up dft_tools and Test using fsanitize=address
-  - mkdir build && cd build
-  - cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=/usr/bin/${CXX} -DCMAKE_CXX_FLAGS='-fsanitize=address -fno-omit-frame-pointer -fuse-ld=gold'
-  - make -j8
-  - export ASAN_SYMBOLIZER_PATH=/usr/lib/llvm-5.0/bin/llvm-symbolizer
-  - export ASAN_OPTIONS=symbolize=1:detect_leaks=0
-  - export CTEST_OUTPUT_ON_FAILURE=1
-  - if [ "$CXX" = g++ ]; then export LD_PRELOAD=/usr/lib/gcc/x86_64-linux-gnu/7/libasan.so; elif [ "$CXX" = clang++ ]; then export LD_PRELOAD=/usr/lib/llvm-5.0/lib/clang/5.0.1/lib/linux/libclang_rt.asan-x86_64.so; fi
-  - cd test && ctest

AUTHORS.txt

@@ -0,0 +1,16 @@
+Markus Aichhorn
+Sophie Beck
+Michel Ferrero
+Alexander Hampel
+Alyn James
+Jonathan Karp
+Gernot Kraberger
+Max Merkel
+Olivier Parcollet
+Oleg Peil
+Leonid Poyurovskiy
+Hermann Schnait
+Malte Schueler
+Dylan Simon
+Nils Wentzell
+Manuel Zingl

CMakeLists.txt

@@ -1,105 +1,178 @@
-# Start configuration
-cmake_minimum_required(VERSION 3.0.2 FATAL_ERROR)
-project(triqs_dft_tools C CXX Fortran)
-if(POLICY CMP0074)
-  cmake_policy(SET CMP0074 NEW)
+# ##############################################################################
+#
+# triqs_dft_tools - An example application using triqs and cpp2py
+#
+# Copyright (C) ...
+#
+# triqs_dft_tools is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# triqs_dft_tools is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# triqs_dft_tools (in the file COPYING.txt in this directory). If not, see
+# <http://www.gnu.org/licenses/>.
+#
+# ##############################################################################
+
+cmake_minimum_required(VERSION 3.12.4 FATAL_ERROR)
+cmake_policy(VERSION 3.12.4)
+if(POLICY CMP0077)
+  cmake_policy(SET CMP0077 NEW)
 endif()
 
+# ############
+# Define Project
+project(triqs_dft_tools VERSION 3.1.0 LANGUAGES C CXX Fortran)
+get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)
+
+# ############
+# Load TRIQS and CPP2PY
+find_package(TRIQS 3.1 REQUIRED)
+
+# Get the git hash & print status
+triqs_get_git_hash_of_source_dir(PROJECT_GIT_HASH)
+message(STATUS "${PROJECT_NAME} version : ${PROJECT_VERSION}")
+message(STATUS "${PROJECT_NAME} Git hash: ${PROJECT_GIT_HASH}")
+
+# Enforce Consistent Versioning
+if(NOT ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR} VERSION_EQUAL ${TRIQS_VERSION_MAJOR}.${TRIQS_VERSION_MINOR})
+  message(FATAL_ERROR "The ${PROJECT_NAME} version ${PROJECT_VERSION} is not compatible with TRIQS version ${TRIQS_VERSION}.")
+endif()
+
+# Default Install directory to TRIQS_ROOT if not given or invalid.
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT OR (NOT IS_ABSOLUTE ${CMAKE_INSTALL_PREFIX}))
+  message(STATUS "No install prefix given (or invalid). Defaulting to TRIQS_ROOT")
+  set(CMAKE_INSTALL_PREFIX ${TRIQS_ROOT} CACHE PATH "default install path" FORCE)
+  set(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT FALSE)
+endif()
+if(NOT IS_SUBPROJECT)
+  message(STATUS "-------- CMAKE_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX} --------")
+endif()
+set(${PROJECT_NAME}_BINARY_DIR ${PROJECT_BINARY_DIR} CACHE STRING "Binary directory of the ${PROJECT_NAME} Project")
+
+# Make additional Find Modules available
+list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/share/cmake/Modules)
+
+# ############
+# CMake Options
+
 # Default to Release build type
 if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE Release CACHE STRING "Type of build" FORCE)
 endif()
-message( STATUS "-------- BUILD-TYPE: ${CMAKE_BUILD_TYPE} --------")
-
-# Use shared libraries
-set(BUILD_SHARED_LIBS ON)
-
-# Load TRIQS and Cpp2Py
-find_package(TRIQS 2.2 REQUIRED)
-find_package(Cpp2Py 1.6 REQUIRED)
-
-if (NOT ${TRIQS_WITH_PYTHON_SUPPORT})
- MESSAGE(FATAL_ERROR "dft_tools require Python support in TRIQS")
+if(NOT IS_SUBPROJECT)
+  message(STATUS "-------- BUILD-TYPE: ${CMAKE_BUILD_TYPE} --------")
 endif()
 
-# Default Install directory to TRIQS_ROOT if not given. Checks an absolute name is given.
-if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT OR (NOT IS_ABSOLUTE ${CMAKE_INSTALL_PREFIX}))
-  message(STATUS " No install prefix given (or invalid). Defaulting to TRIQS_ROOT")
-  set(CMAKE_INSTALL_PREFIX ${TRIQS_ROOT} CACHE PATH "default install path" FORCE)
+# Python Support
+option(PythonSupport "Build with Python support" ON)
+if(PythonSupport AND NOT TRIQS_WITH_PYTHON_SUPPORT)
+  message(FATAL_ERROR "TRIQS was installed without Python support. Cannot build the Python Interface. Disable the build with -DPythonSupport=OFF")
 endif()
-message(STATUS "-------- CMAKE_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX} -------------")
 
-# Define the dft_tools version numbers and get the git hash
-set(DFT_TOOLS_VERSION_MAJOR 2)
-set(DFT_TOOLS_VERSION_MINOR 2)
-set(DFT_TOOLS_VERSION_PATCH 0)
-set(DFT_TOOLS_VERSION ${DFT_TOOLS_VERSION_MAJOR}.${DFT_TOOLS_VERSION_MINOR}.${DFT_TOOLS_VERSION_PATCH})
-triqs_get_git_hash_of_source_dir(DFT_TOOLS_GIT_HASH)
-message(STATUS "Dft_tools version : ${DFT_TOOLS_VERSION}")
-message(STATUS "Git hash: ${DFT_TOOLS_GIT_HASH}")
+# Documentation
+option(Build_Documentation "Build documentation" OFF)
+if(Build_Documentation AND NOT PythonSupport)
+  message(FATAL_ERROR "Build_Documentation=ON requires PythonSupport to be enabled")
+endif()
 
+# Testing
+option(Build_Tests "Build tests" ON)
+if(Build_Tests)
+  enable_testing()
+endif()
+
+# Build static libraries by default
+option(BUILD_SHARED_LIBS "Enable compilation of shared libraries" OFF)
+
+# ############
+# Global Compilation Settings
+
+# Export the list of compile-commands into compile_commands.json
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# Disable compiler extensions
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Provide additional debugging information for Debug builds
+add_compile_options($<$<CONFIG:Debug>:-ggdb3>)
+
+# Create an Interface target for compiler warnings
+add_library(${PROJECT_NAME}_warnings INTERFACE)
+target_compile_options(${PROJECT_NAME}_warnings
+  INTERFACE
+    -Wall
+    -Wextra
+    -Wpedantic
+    -Wno-sign-compare
+    $<$<CXX_COMPILER_ID:GNU>:-Wno-comma-subscript>
+    $<$<CXX_COMPILER_ID:GNU>:-Wshadow=local>
+    $<$<CXX_COMPILER_ID:GNU>:-Wno-attributes>
+    $<$<CXX_COMPILER_ID:Clang>:-Wno-deprecated-comma-subscript>
+    $<$<CXX_COMPILER_ID:Clang>:-Wno-unknown-warning-option>
+    $<$<CXX_COMPILER_ID:Clang>:-Wshadow>
+    $<$<CXX_COMPILER_ID:Clang>:-Wno-gcc-compat>
+    $<$<CXX_COMPILER_ID:Clang>:-Wno-c++20-extensions>
+    $<$<CXX_COMPILER_ID:AppleClang>:-Wno-deprecated-comma-subscript>
+    $<$<CXX_COMPILER_ID:AppleClang>:-Wno-unknown-warning-option>
+    $<$<CXX_COMPILER_ID:AppleClang>:-Wshadow>
+    $<$<CXX_COMPILER_ID:AppleClang>:-Wno-gcc-compat>
+    $<$<CXX_COMPILER_ID:AppleClang>:-Wno-c++20-extensions>
+)
+
+# #############
+# Build Project
+
+# Find / Build dependencies
+add_subdirectory(deps)
+
+# Build and install the library
+add_subdirectory(c++/${PROJECT_NAME})
+
+# add here stuff for the Fortran part in DFTTools
 add_subdirectory(fortran/dmftproj) 
 
-# Add the compiling options (-D... ) for C++
-message(STATUS "TRIQS : Adding compilation flags detected by the library (C++11/14, libc++, etc...) ")
-
-add_subdirectory(c++)
-add_subdirectory(python python/triqs_dft_tools)
-add_subdirectory(shells)
-
-#------------------------
-# tests
-#------------------------
-
-option(TEST_COVERAGE "Analyze the coverage of tests" OFF)
-
-# perform tests with coverage info
-if (${TEST_COVERAGE})
-  # we try to locate the coverage program
-  find_program(PYTHON_COVERAGE python-coverage)
-  find_program(PYTHON_COVERAGE coverage)
-  if(NOT PYTHON_COVERAGE)
-      message(FATAL_ERROR "Program coverage (or python-coverage) not found.\nEither set PYTHON_COVERAGE explicitly or disable TEST_COVERAGE!\nYou need to install the python package coverage, e.g. with\n  pip install coverage\nor with\n  apt install python-coverage")
-  endif()
-
-  message(STATUS "Setting up test coverage")
-  add_custom_target(coverage ${PYTHON_COVERAGE} combine --append .coverage plovasp/.coverage || true COMMAND ${PYTHON_COVERAGE} html COMMAND echo "Open ${CMAKE_BINARY_DIR}/test/htmlcov/index.html in browser!" WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/test)
+# Tests
+if(Build_Tests)
+  add_subdirectory(test)
 endif()
 
-enable_testing()
-
-option(Build_Tests "Build the tests of the library " ON)
-if (Build_Tests)
-  message(STATUS "-------- Preparing tests  -------------")
- add_subdirectory(test)
+# Python
+if(PythonSupport)
+  add_subdirectory(python/${PROJECT_NAME})
 endif()
 
-#------------------------
-# Documentation
-#------------------------
-option(Build_Documentation "Build documentation" OFF)
-if(${Build_Documentation})
-  if(NOT ${TRIQS_WITH_DOCUMENTATION})
-    message("Error: TRIQS library has not been compiled with its documentation")
-  endif()
+# Docs
+if(Build_Documentation)
   add_subdirectory(doc)
 endif()
 
-#--------------------------------------------------------
-# Packaging
-#--------------------------------------------------------
+# dfttols vasp interface bash scripts
+add_subdirectory(bin)
+
+# Additional configuration files
+add_subdirectory(share)
+
+# #############
+# Debian Package
+
 option(BUILD_DEBIAN_PACKAGE "Build a deb package" OFF)
-if(BUILD_DEBIAN_PACKAGE)
+if(BUILD_DEBIAN_PACKAGE AND NOT IS_SUBPROJECT)
   if(NOT CMAKE_INSTALL_PREFIX STREQUAL "/usr")
     message(FATAL_ERROR "CMAKE_INSTALL_PREFIX must be /usr for packaging")
   endif()
-  SET(CPACK_GENERATOR "DEB")
-  SET(CPACK_PACKAGE_VERSION ${DFT_TOOLS_VERSION})
-  SET(CPACK_PACKAGE_CONTACT "https://github.com/TRIQS/dft_tools")
-  EXECUTE_PROCESS(COMMAND dpkg --print-architecture OUTPUT_VARIABLE CMAKE_DEBIAN_PACKAGE_ARCHITECTURE OUTPUT_STRIP_TRAILING_WHITESPACE)
-  SET(CPACK_DEBIAN_PACKAGE_DEPENDS "triqs (>= 2.2)")
-  SET(CPACK_DEBIAN_PACKAGE_CONFLICTS "dft_tools")
-  SET(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
-  SET(CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS ON)
-  INCLUDE(CPack)
+  set(CPACK_PACKAGE_NAME ${PROJECT_NAME})
+  set(CPACK_GENERATOR "DEB")
+  set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
+  set(CPACK_PACKAGE_CONTACT "https://github.com/TRIQS/${PROJECT_NAME}")
+  execute_process(COMMAND dpkg --print-architecture OUTPUT_VARIABLE CMAKE_DEBIAN_PACKAGE_ARCHITECTURE OUTPUT_STRIP_TRAILING_WHITESPACE)
+  set(CPACK_DEBIAN_PACKAGE_DEPENDS "triqs (>= 3.1)")
+  set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+  set(CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS ON)
+  include(CPack)
 endif()

COPYING.txt

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<http://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<http://www.gnu.org/philosophy/why-not-lgpl.html>.

ChangeLog.md

@@ -0,0 +1 @@
+doc/ChangeLog.md

Dockerfile

@@ -1,12 +1,16 @@
 # See ../triqs/packaging for other options
-FROM flatironinstitute/triqs:master-ubuntu-clang
+FROM flatironinstitute/triqs:unstable-ubuntu-clang
+ARG APPNAME=triqs_dft_tools
 
-ARG APPNAME
-COPY . $SRC/$APPNAME
+COPY requirements.txt /src/$APPNAME/requirements.txt
+RUN pip3 install -r /src/$APPNAME/requirements.txt
+
+COPY --chown=build . $SRC/$APPNAME
 WORKDIR $BUILD/$APPNAME
 RUN chown build .
 USER build
-ARG BUILD_DOC=0
-RUN cmake $SRC/$APPNAME -DTRIQS_ROOT=${INSTALL} -DBuild_Documentation=${BUILD_DOC} && make -j2 && make test CTEST_OUTPUT_ON_FAILURE=1
+ARG BUILD_ID
+ARG CMAKE_ARGS
+RUN cmake $SRC/$APPNAME -DTRIQS_ROOT=${INSTALL} $CMAKE_ARGS && make -j4 || make -j1 VERBOSE=1
 USER root
 RUN make install

Jenkinsfile

@@ -1,5 +1,6 @@
 def projectName = "dft_tools" /* set to app/repo name */
 
+def dockerName = projectName.toLowerCase();
 /* which platform to build documentation on */
 def documentationPlatform = "ubuntu-clang"
 /* depend on triqs upstream branch/project */
@@ -24,12 +25,12 @@ def platforms = [:]
 
 /****************** linux builds (in docker) */
 /* Each platform must have a cooresponding Dockerfile.PLATFORM in triqs/packaging */
-def dockerPlatforms = ["ubuntu-clang", "ubuntu-gcc", "centos-gcc"]
+def dockerPlatforms = ["ubuntu-clang", "ubuntu-gcc", "sanitize"]
 /* .each is currently broken in jenkins */
 for (int i = 0; i < dockerPlatforms.size(); i++) {
   def platform = dockerPlatforms[i]
-  platforms[platform] = { -> node('docker') {
-    stage(platform) { timeout(time: 1, unit: 'HOURS') {
+  platforms[platform] = { -> node('linux && docker && triqs') {
+    stage(platform) { timeout(time: 1, unit: 'HOURS') { ansiColor('xterm') {
       checkout scm
       /* construct a Dockerfile for this base */
       sh """
@@ -37,73 +38,98 @@ for (int i = 0; i < dockerPlatforms.size(); i++) {
         mv -f Dockerfile.jenkins Dockerfile
       """
       /* build and tag */
-      def img = docker.build("flatironinstitute/${projectName}:${env.BRANCH_NAME}-${env.STAGE_NAME}", "--build-arg APPNAME=${projectName} --build-arg BUILD_DOC=${platform==documentationPlatform} .")
+      def args = ''
+      if (platform == documentationPlatform)
+        args = '-DBuild_Documentation=1'
+      else if (platform == "sanitize")
+        args = '-DASAN=ON -DUBSAN=ON'
+      def img = docker.build("flatironinstitute/${dockerName}:${env.BRANCH_NAME}-${env.STAGE_NAME}", "--build-arg APPNAME=${projectName} --build-arg BUILD_ID=${env.BUILD_TAG} --build-arg CMAKE_ARGS='${args}' .")
+      catchError(buildResult: 'UNSTABLE', stageResult: 'UNSTABLE') {
+        img.inside() {
+          sh "make -C \$BUILD/${projectName} test CTEST_OUTPUT_ON_FAILURE=1"
+        }
+      }
       if (!keepInstall) {
         sh "docker rmi --no-prune ${img.imageName()}"
       }
-    } }
+    } } }
   } }
 }
 
 /****************** osx builds (on host) */
 def osxPlatforms = [
-  ["gcc", ['CC=gcc-7', 'CXX=g++-7']],
-  ["clang", ['CC=$BREW/opt/llvm/bin/clang', 'CXX=$BREW/opt/llvm/bin/clang++', 'CXXFLAGS=-I$BREW/opt/llvm/include', 'LDFLAGS=-L$BREW/opt/llvm/lib']]
+  ["gcc", ['CC=gcc-11', 'CXX=g++-11', 'FC=gfortran-11']],
+  ["clang", ['CC=$BREW/opt/llvm/bin/clang', 'CXX=$BREW/opt/llvm/bin/clang++', 'FC=gfortran-11', 'CXXFLAGS=-I$BREW/opt/llvm/include', 'LDFLAGS=-L$BREW/opt/llvm/lib']]
 ]
 for (int i = 0; i < osxPlatforms.size(); i++) {
   def platformEnv = osxPlatforms[i]
   def platform = platformEnv[0]
   platforms["osx-$platform"] = { -> node('osx && triqs') {
-    stage("osx-$platform") { timeout(time: 1, unit: 'HOURS') {
+    stage("osx-$platform") { timeout(time: 1, unit: 'HOURS') { ansiColor('xterm') {
       def srcDir = pwd()
       def tmpDir = pwd(tmp:true)
       def buildDir = "$tmpDir/build"
+      /* install real branches in a fixed predictable place so apps can find them */
       def installDir = keepInstall ? "${env.HOME}/install/${projectName}/${env.BRANCH_NAME}/${platform}" : "$tmpDir/install"
       def triqsDir = "${env.HOME}/install/triqs/${triqsBranch}/${platform}"
+      def venv = triqsDir
       dir(installDir) {
         deleteDir()
       }
 
       checkout scm
+
+      def hdf5 = "${env.BREW}/opt/hdf5@1.10"
       dir(buildDir) { withEnv(platformEnv[1].collect { it.replace('\$BREW', env.BREW) } + [
-        "PATH=$triqsDir/bin:${env.BREW}/bin:/usr/bin:/bin:/usr/sbin",
-        "CPLUS_INCLUDE_PATH=$triqsDir/include:${env.BREW}/include",
-        "LIBRARY_PATH=$triqsDir/lib:${env.BREW}/lib",
-        "CMAKE_PREFIX_PATH=$triqsDir/lib/cmake/triqs"]) {
+          "PATH=$venv/bin:${env.BREW}/bin:/usr/bin:/bin:/usr/sbin",
+          "HDF5_ROOT=$hdf5",
+          "C_INCLUDE_PATH=$hdf5/include:${env.BREW}/include",
+          "CPLUS_INCLUDE_PATH=$venv/include:$hdf5/include:${env.BREW}/include",
+          "LIBRARY_PATH=$venv/lib:$hdf5/lib:${env.BREW}/lib",
+          "LD_LIBRARY_PATH=$hdf5/lib",
+          "PYTHONPATH=$installDir/lib/python3.9/site-packages",
+          "CMAKE_PREFIX_PATH=$venv/lib/cmake/triqs",
+          "OMP_NUM_THREADS=2"]) {
         deleteDir()
         /* note: this is installing into the parent (triqs) venv (install dir), which is thus shared among apps and so not be completely safe */
-        sh "pip install -r $srcDir/requirements.txt"
-        sh "cmake $srcDir -DCMAKE_INSTALL_PREFIX=$installDir -DTRIQS_ROOT=$triqsDir"
-        sh "make -j3"
-        try {
+        sh "pip3 install -U -r $srcDir/requirements.txt"
+        sh "cmake $srcDir -DCMAKE_INSTALL_PREFIX=$installDir -DTRIQS_ROOT=$triqsDir -DBuild_Deps=Always"
+        sh "make -j2 || make -j1 VERBOSE=1"
+        catchError(buildResult: 'UNSTABLE', stageResult: 'UNSTABLE') { try {
           sh "make test CTEST_OUTPUT_ON_FAILURE=1"
         } catch (exc) {
           archiveArtifacts(artifacts: 'Testing/Temporary/LastTest.log')
           throw exc
-        }
+        } }
         sh "make install"
       } }
-    } }
+    } } }
   } }
 }
 
 /****************** wrap-up */
+def error = null
 try {
   parallel platforms
-  if (keepInstall) { node("docker") {
+  if (keepInstall) { node('linux && docker && triqs') {
     /* Publish results */
     stage("publish") { timeout(time: 5, unit: 'MINUTES') {
       def commit = sh(returnStdout: true, script: "git rev-parse HEAD").trim()
       def release = env.BRANCH_NAME == "master" || env.BRANCH_NAME == "unstable" || sh(returnStdout: true, script: "git describe --exact-match HEAD || true").trim()
-      def workDir = pwd()
+      def workDir = pwd(tmp:true)
       lock('triqs_publish') {
       /* Update documention on gh-pages branch */
       dir("$workDir/gh-pages") {
         def subdir = "${projectName}/${env.BRANCH_NAME}"
         git(url: "ssh://git@github.com/TRIQS/TRIQS.github.io.git", branch: "master", credentialsId: "ssh", changelog: false)
         sh "rm -rf ${subdir}"
-        docker.image("flatironinstitute/${projectName}:${env.BRANCH_NAME}-${documentationPlatform}").inside() {
-          sh "cp -rp \$INSTALL/share/doc/triqs_${projectName} ${subdir}"
+        docker.image("flatironinstitute/${dockerName}:${env.BRANCH_NAME}-${documentationPlatform}").inside() {
+          sh """#!/bin/bash -ex
+            base=\$INSTALL/share/doc
+            dir="${projectName}"
+            [[ -d \$base/triqs_\$dir ]] && dir=triqs_\$dir || [[ -d \$base/\$dir ]]
+            cp -rp \$base/\$dir ${subdir}
+          """
         }
         sh "git add -A ${subdir}"
         sh """
@@ -131,13 +157,13 @@ try {
     } }
   } }
 } catch (err) {
+  error = err
+} finally {
   /* send email on build failure (declarative pipeline's post section would work better) */
-  if (env.BRANCH_NAME != "jenkins") emailext(
+  if ((error != null || currentBuild.currentResult != 'SUCCESS') && env.BRANCH_NAME != "jenkins") emailext(
     subject: "\$PROJECT_NAME - Build # \$BUILD_NUMBER - FAILED",
     body: """\$PROJECT_NAME - Build # \$BUILD_NUMBER - FAILED
 
-$err
-
 Check console output at \$BUILD_URL to view full results.
 
 Building \$BRANCH_NAME for \$CAUSE
@@ -149,11 +175,11 @@ Changes:
 End of build log:
 \${BUILD_LOG,maxLines=60}
     """,
-    to: 'mzingl@flatironinstitute.org, hstrand@flatironinstitute.org, nwentzell@flatironinstitute.org, dsimon@flatironinstitute.org',
+    to: 'ahampel@flatironinstitute.org, nwentzell@flatironinstitute.org, dsimon@flatironinstitute.org',
     recipientProviders: [
       [$class: 'DevelopersRecipientProvider'],
     ],
     replyTo: '$DEFAULT_REPLYTO'
   )
-  throw err
+  if (error != null) throw error
 }

LICENSE.txt

@@ -0,0 +1,17 @@
+TRIQS: a Toolbox for Research in Interacting Quantum Systems
+
+Copyright (C) 2013-2020 The Authors (c.f. AUTHORS.txt)
+Copyright (C) 2018-2020 The Simons Foundation
+
+TRIQS is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+ 
+TRIQS is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+TRIQS (in the file COPYING.txt in this directory). If not, see
+<http://www.gnu.org/licenses/>.

README.md

@@ -1,15 +1,15 @@
-Wien2TRIQS interface to Wien2k
-Copyright (C) 2011-2013, M. Aichhorn, L. Pourovskii, V. Vildosola and C. Martins
+DFT_Tools - A TRIQS application for ab initio calculations
+ 
+Copyright (C) 2011-2019: M. Aichhorn, L. Pourovskii, V. Vildosola and C. Martins
+Copyright (C) 2020-2022: The Simons Foundation
 
 1. Documentation
 
-You will find the documentation of this application under
-<https://triqs.github.io/dft_tools/>.
+You will find the documentation of this application under [triqs.github.io/dft_tools](https://triqs.github.io/dft_tools/).
 
 2. Installation
 
-The installation steps are described in
-<https://triqs.github.io/dft_tools/2.1.x/install.html>
+The installation steps are described in [triqs.github.io/dft_tools/latest/install](https://triqs.github.io/dft_tools/latest/install.html)
 
 3. Version
 

bin/CMakeLists.txt

@@ -1,9 +1,13 @@
 
-configure_file(plovasp.bash.in plovasp)
+configure_file(plovasp.in plovasp)
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/plovasp DESTINATION bin
         PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
 
-configure_file(vasp_dmft.bash.in vasp_dmft)
+configure_file(vasp_dmft.in vasp_dmft)
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/vasp_dmft DESTINATION bin
         PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
 
+configure_file(init_dmftpr.in init_dmftpr)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/init_dmftpr DESTINATION bin
+        PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
+

bin/init_dmftpr.in

@@ -0,0 +1,124 @@
+#!/usr/bin/env python
+import glob, sys, os
+from numpy import array
+
+def write_indmftpr():
+    """
+    Usage: init_dmftpr
+    
+    **case.struct file is required for this script.**
+
+    An interactive script to generate the input file (case.indmftpr) for
+    the dmftproj program.
+    """
+    orbitals = {"s" : [1, 0, 0, 0],
+                "p" : [0, 1, 0, 0],
+                "d" : [0, 0, 1, 0], 
+                "f" : [0, 0, 0, 1]}
+    corr_orbitals = {"s" : [2, 0, 0, 0],
+                     "p" : [0, 2, 0, 0],
+                     "d" : [0, 0, 2, 0], 
+                     "f" : [0, 0, 0, 2]}
+    dirname = os.getcwd().rpartition('/')[2]
+    if os.path.isfile(dirname + ".indmftpr"):
+       found = input("Previous {}.indmftpr detected! Continue? (y/n)\n".format(dirname))
+       if found == "n": sys.exit(0)
+    with open(dirname + ".indmftpr", "w") as out:
+        print("Preparing dmftproj input file : {}\n".format(dirname + ".indmftpr"))
+        if not os.path.isfile(dirname + ".struct"): print("Could not identify a case.struct file!"); sys.exit(-1);
+        struct = open(glob.glob("*.struct")[0], "r").readlines()
+        species = [line.split()[0] for line in struct if "NPT" in line]
+        num_atoms = len(species)
+        print("number of atoms = {} ({})\n".format(str(num_atoms), " ".join(species)))
+        out.write(str(num_atoms)+"\n")
+        mult = [line.split("=")[1].split()[0] for line in struct if "MULT" in line ]
+        out.write(" ".join(mult)+"\n")
+        out.write("3\n") 
+        for atom in range(num_atoms):
+            while True: # input choice of spherical harmonics for atom
+                sph_harm=input("What flavor of spherical harmonics do you want to use for ATOM {} ({})? (cubic/complex/fromfile)\n".format(atom+1, species[atom]))
+                if sph_harm in ["cubic", "complex", "fromfile"]:
+                    out.write(sph_harm+"\n")
+                    if sph_harm == "fromfile":
+                        filename=input("name of file defining the basis?\n")
+                        if len(filename) < 25: # name of file must be less than 25 characters
+                            out.write(filename)
+                        else:
+                            print("{} is too long!".format(filename))
+                            rename=input("Rename the file to: \n")
+                            if os.path.isfile(filename):
+                                os.rename(filename, rename)
+                                out.write(rename+"\n")
+                            else:
+                                print("{} could not be found in the current directory!".format(filename))
+                                sys.exit(1)
+                    break
+
+                else:
+                    print("Did not recognize that input. Try again.")
+
+            corr=input("Do you want to treat ATOM {} ({}) as correlated (y/n)?\n".format(atom+1, species[atom]))
+            if corr == "y":
+                proj=input("Specify the correlated orbital? (d,f)\n")
+                while True:
+                    non_corr=input("projectors for non-correlated orbitals? (type h for help)\n")
+                    if non_corr == "h":
+                        print("indicate orbital projectors using (s, p, d, or f). For multiple, combine them (sp, pd, spd, etc.)")
+                    elif len(non_corr) > 0 and proj in non_corr:
+                        print("Error: User can not choose orbital {} as both correlated and uncorrelated!".format(proj))
+                    else:
+                        projectors=array([0, 0, 0, 0])
+                        projectors += array(corr_orbitals[proj])
+                        if len(non_corr) > 0:
+                            for p in non_corr: projectors += array(orbitals[p])
+                        out.write(" ".join(list(map(str, projectors)))+"\n")
+                        break
+                to_write = "0 0 0 0\n"
+                if proj == "d":
+                    irrep=input("Split this orbital into it's irreps? (t2g/eg/n)\n")
+                    if irrep == "t2g":
+                        to_write = "0 0 2 0\n01\n"
+                    elif irrep == "eg":
+                        to_write = "0 0 2 0\n10\n"
+
+                soc=input("Do you want to include soc? (y/n)\n")
+                if soc == "y":
+                    if proj=="d" and ( irrep == "t2g" or irrep == "eg" ):
+                        print("Warning: For SOC, dmftproj will use the entire d-shell. Using entire d-shell!")
+                        out.write("0 0 0 0\n")
+                        out.write("1\n")
+                    else:
+                        out.write(to_write)
+                        out.write("1\n")
+                else:
+                    out.write(to_write)
+                    out.write("0\n")
+
+            else: # still identify the projectors
+                while True:
+                    proj=input("Specify the projectors that you would like to include? (type h for help)\n")
+                    if proj == "h":
+                        print("indicate orbital projectors using (s, p, d, or f). For multiple, combine them (sp, pd, spd, etc.)")
+                    else:
+                        projectors = array([0, 0, 0, 0], dtype=int)
+                        for p in proj: projectors += array(orbitals[p], dtype=int)
+                        out.write(" ".join(list(map(str, projectors)))+"\n")
+                        out.write("0 0 0 0\n")
+                        break
+        while True:
+            window=input("Specify the projection window around eF (default unit is Ry, specify eV with -X.XX X.XX eV)\n")
+            if float(window.split()[0]) < 0 and float(window.split()[1]) > 0:
+                try:
+                    eV2Ry=1.0/13.60566
+                    if window.split()[2] == "ev" or window.split()[2] == "eV" or window.split()[2] == "Ev":
+                        out.write("{0:0.2f} {1:0.2f}".format(float(window.split()[0])*eV2Ry, float(window.split()[1])*eV2Ry))
+                except:
+                    out.write(window)
+                break
+            else:
+                print("The energy window ({}) does not contain the Fermi energy!".format(window))
+    print("initialize {} file ok!".format(dirname + ".indmftpr"))
+
+
+if __name__ == "__main__":
+    write_indmftpr()

bin/plovasp.in

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+@TRIQS_PYTHON_EXECUTABLE@ -m triqs_dft_tools.converters.plovasp.converter $@
+

bin/vasp_dmft.in

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+MPIRUN_CMD=mpirun
+
+show_help()
+{
+echo "
+Usage: vasp_dmft [-n <number of cores>] -i <number of iterations>  -j <number of VASP iterations with fixed charge density> [-v <VASP version>] [-p <path to VASP directory>] [<dmft_script.py>]
+
+       If the number of cores is not specified it is set to 1 by default.
+
+       Set the number of times the dmft solver is called with -i <number of iterations>
+
+       Set the number of VASP iteration with a fixed charge density update
+       inbetween the dmft runs with -j <number of VASP iterations with fixed charge density>
+
+       Set the version of VASP by -v standard(default)/no_gamma_write to
+       specify if VASP writes the GAMMA file or not.
+
+       If the path to VASP directory is not specified it must be provided by a
+       variable VASP_DIR.
+
+       <dmft_script.py> must provide an importable function 'dmft_cycle()'
+       which is invoked once per DFT+DMFT iteration. If the script name is
+       omitted the default name 'csc_dmft.py' is used.
+       
+       
+"
+}
+
+while getopts ":n:i:j:v:p:h" opt; do
+  case $opt in
+     n)
+#        echo "Option: Ncpu, argument: $OPTARG"
+        if [ -n "$OPTARG" ]; then
+           NPROC=$OPTARG
+#           echo "Number of cores: $NPROC"
+        fi
+        ;;
+     i)
+#        echo "Option: Niter"
+        if [ -n "$OPTARG" ]; then
+           NITER=$OPTARG
+#           echo "Number of iterations: $NITER"
+        fi
+        ;;
+     j)
+#        echo "Option: Ndftiter"
+        if [ -n "$OPTARG" ]; then
+           NDFTITER=$OPTARG
+#           echo "Number of iterations with fixed density: $NDFTITER"
+        fi
+        ;;
+     p)
+        if [ -n "$OPTARG" ]; then
+           VASP_DIR=$OPTARG
+        fi
+        ;;
+     v)
+        if [ -n "$OPTARG" ]; then
+           VASP_VERSION=$OPTARG
+#           echo "Version of VASP (writing GAMMA file (standard) or not (no_gamma_write): $VASP_VERSION"
+        fi
+        ;;
+      h)
+        show_help
+        exit 1
+        ;;
+      :)
+        echo "  Error: Option -$OPTARG requires an argument" >&2
+        show_help
+        exit 1
+        ;;
+     \?)
+        echo "  Error: Invalid option -$OPTARG" >&2
+  esac
+done
+
+if [ -z "$NITER" ]; then
+  echo "  Error: Number of iterations must be specified with option -i" >&2
+  show_help
+  exit 1
+fi
+
+
+if [ -z "$VASP_DIR" ]; then
+  echo "  Error: A path to VASP directory must be given either with option -p or by setting variable VASP_DIR" >&2
+  show_help
+  exit 1
+fi
+
+if [ -z "$NPROC" ]; then
+  echo "  Number of cores not specified, setting to 1"
+  NPROC=1
+fi
+
+if [ -z "$NDFTITER" ]; then
+  echo "  Number of VASP iterations without updating density not specified, setting to 1"
+  NDFTITER=1
+fi
+
+if [ -z "$VASP_VERSION" ]; then
+  echo "  VASP version not specified, setting to standard"
+  VASP_VERSION="standard"
+fi
+
+shift $((OPTIND-1))
+
+if [ -z "$1" ]; then
+  DMFT_SCRIPT=csc_dmft.py
+else
+  DMFT_SCRIPT=$1
+fi
+
+echo "  Number of cores: $NPROC"
+echo "  Number of iterations: $NITER"
+echo "  Number of iterations with fixed density: $NDFTITER"
+echo "  VASP version: $VASP_VERSION"
+echo "  Script name: $DMFT_SCRIPT"
+
+rm -f vasp.lock
+stdbuf -o 0 $MPIRUN_CMD -np $NPROC "$VASP_DIR" &
+
+
+$MPIRUN_CMD -np $NPROC @TRIQS_PYTHON_EXECUTABLE@ -m triqs_dft_tools.converters.plovasp.sc_dmft $(jobs -p) $NITER $NDFTITER $DMFT_SCRIPT 'plo.cfg' $VASP_VERSION || kill %1
+

c++/plovasp/atm/.gitignore

@@ -1,5 +0,0 @@
-makefile
-Makefile
-*.so
-*.o
-*.pyc

c++/plovasp/atm/CMakeLists.txt

@@ -1,7 +0,0 @@
-add_library(atm_c dos_tetra3d.hpp dos_tetra3d.cpp argsort.hpp argsort.cpp)
-target_link_libraries(atm_c triqs)
-target_compile_options(atm_c PRIVATE -std=c++17)
-
-install(TARGETS atm_c DESTINATION lib)
-
-add_subdirectory(test)

c++/plovasp/atm/test/CMakeLists.txt

@@ -1,13 +0,0 @@
-enable_testing()
-
-FILE(GLOB TestList RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)
-FOREACH( TestName1  ${TestList} )
- STRING(REPLACE ".cpp" "" TestName ${TestName1})
- add_executable( ${TestName}  ${TestName}.cpp )
- target_link_libraries( ${TestName} atm_c triqs)
- triqs_set_rpath_for_target( ${TestName} )
- add_test(NAME ${TestName} COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${t})
-ENDFOREACH( TestName1  ${TestList} )
-
-
-

c++/triqs_dft_tools/CMakeLists.txt

@@ -0,0 +1,84 @@
+file(GLOB_RECURSE sources *.cpp)
+add_library(${PROJECT_NAME}_c ${sources})
+add_library(${PROJECT_NAME}::${PROJECT_NAME}_c ALIAS ${PROJECT_NAME}_c)
+
+# Link against triqs and enable warnings
+target_link_libraries(${PROJECT_NAME}_c PUBLIC triqs PRIVATE $<BUILD_INTERFACE:${PROJECT_NAME}_warnings>)
+
+# Configure target and compilation
+set_target_properties(${PROJECT_NAME}_c PROPERTIES
+  POSITION_INDEPENDENT_CODE ON
+  VERSION ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}
+)
+target_include_directories(${PROJECT_NAME}_c PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/c++>)
+target_include_directories(${PROJECT_NAME}_c SYSTEM INTERFACE $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include>)
+target_compile_definitions(${PROJECT_NAME}_c PUBLIC
+				TRIQS_DFT_TOOLS_GIT_HASH=${PROJECT_GIT_HASH}
+				TRIQS_GIT_HASH=${TRIQS_GIT_HASH}
+				$<$<CONFIG:Debug>:TRIQS_DFT_TOOLS_DEBUG>
+				$<$<CONFIG:Debug>:TRIQS_DEBUG>
+				$<$<CONFIG:Debug>:TRIQS_ARRAYS_ENFORCE_BOUNDCHECK>
+			  )
+
+# Install library and headers
+install(TARGETS ${PROJECT_NAME}_c EXPORT ${PROJECT_NAME}-targets DESTINATION lib)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} DESTINATION include FILES_MATCHING PATTERN "*.hpp" PATTERN "*.h")
+
+
+# ========= Static Analyzer Checks ==========
+
+option(ANALYZE_SOURCES OFF "Run static analyzer checks if found (clang-tidy, cppcheck)")
+if(ANALYZE_SOURCES)
+
+  # Locate static analyzer tools
+  find_program(CPPCHECK_EXECUTABLE NAMES "cppcheck" PATHS ENV PATH)
+  find_program(CLANG_TIDY_EXECUTABLE NAMES "clang-tidy" PATHS ENV PATH)
+
+  # Run clang-tidy if found
+  if(CLANG_TIDY_EXECUTABLE)
+    message(STATUS "clang-tidy found: ${CLANG_TIDY_EXECUTABLE}")
+    set_target_properties(${PROJECT_NAME}_c PROPERTIES CXX_CLANG_TIDY "${CLANG_TIDY_EXECUTABLE}")
+  else()
+    message(STATUS "clang-tidy not found in $PATH. Please consider installing clang-tidy for additional checks!")
+  endif()
+
+  # Run cppcheck if found
+  if(CPPCHECK_EXECUTABLE)
+    message(STATUS "cppcheck found: ${CPPCHECK_EXECUTABLE}")
+    add_custom_command(
+	TARGET ${PROJECT_NAME}_c
+	COMMAND ${CPPCHECK_EXECUTABLE}
+	  --enable=warning,style,performance,portability
+	  --std=c++20
+	  --template=gcc
+	  --verbose
+	  --force
+	  --quiet
+          ${sources}
+	WORKING_DIRECTORY
+	  ${CMAKE_CURRENT_SOURCE_DIR}
+    )
+  else()
+    message(STATUS "cppcheck not found in $PATH. Please consider installing cppcheck for additional checks!")
+  endif()
+
+endif()
+
+
+# ========= Dynamic Analyzer Checks ==========
+
+option(ASAN OFF "Compile library and executables with LLVM Address Sanitizer")
+option(UBSAN OFF "Compile library and executables with LLVM Undefined Behavior Sanitizer")
+
+if(ASAN)
+  if(NOT TARGET asan)
+    find_package(sanitizer REQUIRED "asan")
+  endif()
+  target_link_libraries(${PROJECT_NAME}_c PUBLIC $<BUILD_INTERFACE:asan>)
+endif()
+if(UBSAN)
+  if(NOT TARGET ubsan)
+    find_package(sanitizer REQUIRED "ubsan")
+  endif()
+  target_link_libraries(${PROJECT_NAME}_c PUBLIC $<BUILD_INTERFACE:ubsan>)
+endif()

c++/triqs_dft_tools/converters/vasp.hpp

@@ -0,0 +1,3 @@
+#pragma once
+#include "./vasp/argsort.hpp"
+#include "./vasp/dos_tetra3d.hpp"

c++/triqs_dft_tools/converters/vasp/dos_tetra3d.cpp

@@ -18,7 +18,7 @@
 * TRIQS. If not, see <http://www.gnu.org/licenses/>.
 *
 *******************************************************************************/
-#include <triqs/arrays.hpp>
+#include <nda/nda.hpp>
 #include <iostream>
 #include <complex>
 
@@ -28,8 +28,8 @@
 //#define __TETRA_DEBUG
 #define __TETRA_ARRAY_VIEW
 
-using triqs::arrays::array;
-using triqs::arrays::array_view;
+using nda::array;
+using nda::array_view;
 
 /***************************************************
 
@@ -79,12 +79,12 @@ array<double, 2> dos_tetra_weights_3d(array<double, 1> eigk, double en, array<lo
   int ntet; /// Number of tetrahedra
 // Auxiliary variables and loop indices
 
-  if (first_dim(itt) != NUM_TET_CORNERS + 1)
+  if (itt.shape()[0] != NUM_TET_CORNERS + 1)
   {
-      TRIQS_RUNTIME_ERROR << "  The first dimension of 'itt' must be equal to 5";
+      NDA_RUNTIME_ERROR << "  The first dimension of 'itt' must be equal to 5";
   }
 
-  ntet = second_dim(itt);
+  ntet = itt.shape()[1];
 
   array<double, 2> cti(NUM_TET_CORNERS, ntet); // Corner weights to be returned
 

c++/triqs_dft_tools/converters/vasp/dos_tetra3d.hpp

@@ -20,18 +20,16 @@
 *******************************************************************************/
 #pragma once
 
-#include <triqs/arrays.hpp>
+#include <nda/nda.hpp>
 
-using triqs::arrays::array;
-using triqs::arrays::array_view;
 
 /// DOS of a band by analytical tetrahedron method
 ///
 ///   Returns corner weights for all tetrahedra for a given band and real energy.
-array<double, 2>
-dos_tetra_weights_3d(array_view<double, 1> eigk, /// Band energies for each k-point
+nda::array<double, 2>
+dos_tetra_weights_3d(nda::array_view<double, 1> eigk, /// Band energies for each k-point
                      double en, /// Energy at which DOS weights are to be calculated
-                     array_view<long, 2> itt /// Tetrahedra defined by k-point indices
+                     nda::array_view<long, 2> itt /// Tetrahedra defined by k-point indices
 );
 //array<double, 2> 
 //dos_tetra_weights_3d(array<double, 1> eigk, /// Band energies for each k-point

c++/triqs_dft_tools/triqs_dft_tools.hpp

@@ -0,0 +1,3 @@
+#pragma once
+#include "./converters/vasp.hpp"
+

cmake/sitecustomize.py

@@ -1,8 +0,0 @@
-def application_pytriqs_import(name,*args,**kwargs):
-  if name.startswith('@package_name@'):
-    name = name[len('@package_name@')+1:]
-  return builtin_import(name,*args,**kwargs)
-
-import __builtin__
-__builtin__.__import__, builtin_import = application_pytriqs_import, __builtin__.__import__
-

deps/.gitignore

@@ -0,0 +1 @@
+*

deps/CMakeLists.txt

@@ -0,0 +1,67 @@
+include(external_dependency.cmake)
+
+# Add your dependencies with the function
+#
+#   external_dependency(name
+#       [VERSION <version-number>]
+#       [GIT_REPO <url>]
+#       [GIT_TAG <tag>]
+#       [BUILD_ALWAYS]
+#       [EXCLUDE_FROM_ALL]
+#   )
+#
+# Resolve the dependency using the following steps in order.
+# If a step was successful, skip the remaining ones.
+#
+#  1. Use find_package(name [<version-number>])
+#     to locate the package in the system.
+#     Skip this step if Build_Deps option is set.
+#  2. Try to find a directory containing the sources
+#     at ${CMAKE_CURRENT_SOURCE_DIR}/name and
+#     ${CMAKE_SOURCE_DIR}/deps/name. If found
+#     build it as a cmake sub-project.
+#  3. If GIT_REPO is provided, git clone the sources,
+#     and build them as a cmake sub-project.
+#
+# Addtional options:
+#
+#  GIT_TAG - Use this keyword to specify the git-tag, branch or commit hash
+#
+#  BUILD_ALWAYS - If set, this dependency will always be built from source
+#                 and will never be searched in the system.
+#
+#  EXCLUDE_FROM_ALL - If set, targets of the dependency cmake subproject
+#                     will not be included in the ALL target of the project.
+#                     In particular the dependency will not be installed.
+
+if(NOT DEFINED Build_Deps)
+  set(Build_Deps "Always" CACHE STRING "Do we build dependencies from source? [Never/Always/IfNotFound]")
+else()
+  set(Build_Deps_Opts "Never" "Always" "IfNotFound")
+  if(NOT ${Build_Deps} IN_LIST Build_Deps_Opts)
+    message(FATAL_ERROR "Build_Deps option should be either 'Never', 'Always' or 'IfNotFound'")
+  endif()
+  set(Build_Deps ${Build_Deps} CACHE STRING "Do we build dependencies from source? [Never/Always/IfNotFound]")
+  if(NOT IS_SUBPROJECT AND NOT Build_Deps STREQUAL "Always" AND (ASAN OR UBSAN))
+    message(WARNING "For builds with llvm sanitizers (ASAN/UBSAN) it is recommended to use -DBuild_Deps=Always to avoid false positives.")
+  endif()
+endif()
+
+# -- Cpp2Py --
+if(PythonSupport OR Build_Documentation)
+  external_dependency(Cpp2Py
+    GIT_REPO https://github.com/TRIQS/cpp2py
+    VERSION 2.0
+    GIT_TAG master
+    BUILD_ALWAYS
+    EXCLUDE_FROM_ALL
+  )
+endif()
+
+# -- GTest --
+external_dependency(GTest
+  GIT_REPO https://github.com/google/googletest
+  GIT_TAG main
+  BUILD_ALWAYS
+  EXCLUDE_FROM_ALL
+)

deps/external_dependency.cmake

@@ -0,0 +1,95 @@
+# Copyright (c) 2020 Simons Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You may obtain a copy of the License at
+#     https://www.gnu.org/licenses/gpl-3.0.txt
+
+
+# Consider ROOT env variables in find_package
+if(POLICY CMP0074)
+  cmake_policy(SET CMP0074 NEW)
+endif()
+
+# Make sure that imported targets are always global
+get_property(IMPORTED_ALWAYS_GLOBAL GLOBAL PROPERTY IMPORTED_ALWAYS_GLOBAL)
+if(NOT IMPORTED_ALWAYS_GLOBAL)
+  function(add_library)
+    set(_args ${ARGN})
+    if ("${_args}" MATCHES ";IMPORTED")
+        list(APPEND _args GLOBAL)
+    endif()
+    _add_library(${_args})
+  endfunction()
+  set_property(GLOBAL PROPERTY IMPORTED_ALWAYS_GLOBAL TRUE)
+endif()
+
+# Define External Dependency Function
+function(external_dependency)
+  cmake_parse_arguments(ARG "EXCLUDE_FROM_ALL;BUILD_ALWAYS" "VERSION;GIT_REPO;GIT_TAG" "" ${ARGN})
+
+  # -- Was dependency already found?
+  get_property(${ARGV0}_FOUND GLOBAL PROPERTY ${ARGV0}_FOUND)
+  if(${ARGV0}_FOUND)
+    message(STATUS "Dependency ${ARGV0} was already resolved.")
+    return()
+  endif()
+
+  # -- Try to find package in system.
+  if(NOT ARG_BUILD_ALWAYS AND NOT Build_Deps STREQUAL "Always")
+    find_package(${ARGV0} ${ARG_VERSION} QUIET HINTS ${CMAKE_INSTALL_PREFIX})
+    if(${ARGV0}_FOUND)
+      message(STATUS "Found dependency ${ARGV0} in system ${${ARGV0}_ROOT}")
+      return()
+    elseif(Build_Deps STREQUAL "Never")
+      message(FATAL_ERROR "Could not find dependency ${ARGV0} in system. Please install the dependency manually or use -DBuild_Deps=IfNotFound during cmake configuration to automatically build all dependencies that are not found.")
+    endif()
+  endif()
+
+  # -- Build package from source
+  message(STATUS " =============== Configuring Dependency ${ARGV0} =============== ")
+  if(ARG_EXCLUDE_FROM_ALL)
+    set(subdir_opts EXCLUDE_FROM_ALL)
+    set(Build_Tests OFF)
+    set(Build_Documentation OFF)
+  endif()
+  if(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${ARGV0})
+    message(STATUS "Found sources for dependency ${ARGV0} at ${CMAKE_CURRENT_SOURCE_DIR}/${ARGV0}")
+    add_subdirectory(${ARGV0} ${subdir_opts})
+  elseif(IS_DIRECTORY ${CMAKE_SOURCE_DIR}/deps/${ARGV0})
+    message(STATUS "Found sources for dependency ${ARGV0} at ${CMAKE_SOURCE_DIR}/deps/${ARGV0}")
+    add_subdirectory(${ARGV0} ${subdir_opts})
+  elseif(ARG_GIT_REPO)
+    set(bin_dir ${CMAKE_CURRENT_BINARY_DIR}/${ARGV0})
+    set(src_dir ${bin_dir}_src)
+    if(NOT IS_DIRECTORY ${src_dir})
+      if(ARG_GIT_TAG)
+        set(clone_opts --branch ${ARG_GIT_TAG} -c advice.detachedHead=false)
+      endif()
+      if(NOT GIT_EXECUTABLE)
+        find_package(Git REQUIRED)
+      endif()
+      execute_process(COMMAND ${GIT_EXECUTABLE} clone ${ARG_GIT_REPO} --depth 1 ${clone_opts} ${src_dir}
+        RESULT_VARIABLE clone_failed
+        ERROR_VARIABLE clone_error
+      )
+      if(clone_failed)
+        message(FATAL_ERROR "Failed to clone sources for dependency ${ARGV0}.\n ${clone_error}")
+      endif()
+    endif()
+    add_subdirectory(${src_dir} ${bin_dir} ${subdir_opts})
+  else()
+    message(FATAL_ERROR "Could not find or build dependency ${ARGV0}")
+  endif()
+  message(STATUS " =============== End ${ARGV0} Configuration =============== ")
+  set_property(GLOBAL PROPERTY ${ARGV0}_FOUND TRUE)
+
+endfunction()

doc/CMakeLists.txt

@@ -1,23 +1,81 @@
-# generate the conf.py
+# Generate the sphinx config file
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
 
+# -----------------------------------------------------------------------------
+# Create an optional target that allows us to regenerate the C++ doc with c++2rst
+# -----------------------------------------------------------------------------
+add_custom_target(${PROJECT_NAME}_docs_cpp2rst)
+include(${PROJECT_SOURCE_DIR}/share/cmake/extract_flags.cmake)
+extract_flags(${PROJECT_NAME}_c BUILD_INTERFACE)
+separate_arguments(${PROJECT_NAME}_c_CXXFLAGS)
+macro(generate_docs header_file)
+  add_custom_command(
+    TARGET ${PROJECT_NAME}_docs_cpp2rst
+    COMMAND rm -rf ${CMAKE_CURRENT_SOURCE_DIR}/cpp2rst_generated
+    COMMAND
+      PYTHONPATH=${CPP2PY_BINARY_DIR}:$ENV{PYTHONPATH}
+      PATH=${CPP2PY_BINARY_DIR}/bin:${CPP2PY_ROOT}/bin:$ENV{PATH}
+      c++2rst
+      ${header_file}
+      -N ${PROJECT_NAME}
+      --output_directory ${CMAKE_CURRENT_SOURCE_DIR}/cpp2rst_generated
+      -I${PROJECT_SOURCE_DIR}/c++
+      --cxxflags="${${PROJECT_NAME}_c_CXXFLAGS}"
+  )
+endmacro(generate_docs)
+
+generate_docs(${PROJECT_SOURCE_DIR}/c++/${PROJECT_NAME}/${PROJECT_NAME}.hpp)
+
+# --------------------------------------------------------
+# Build & Run the C++ doc examples and capture the output
+# --------------------------------------------------------
+
+add_custom_target(${PROJECT_NAME}_docs_example_output)
+file(GLOB_RECURSE ExampleList RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)
+foreach(example ${ExampleList})
+  get_filename_component(f ${example} NAME_WE)
+  get_filename_component(d ${example} DIRECTORY)
+  add_executable(${PROJECT_NAME}_doc_${f} EXCLUDE_FROM_ALL ${example})
+  set_property(TARGET ${PROJECT_NAME}_doc_${f} PROPERTY RUNTIME_OUTPUT_DIRECTORY ${d})
+  target_link_libraries(${PROJECT_NAME}_doc_${f} triqs)
+  add_custom_command(TARGET ${PROJECT_NAME}_doc_${f}
+   COMMAND ${PROJECT_NAME}_doc_${f} > ${CMAKE_CURRENT_SOURCE_DIR}/${d}/${f}.output 2>/dev/null
+   WORKING_DIRECTORY ${d}
+  )
+  add_dependencies(${PROJECT_NAME}_docs_example_output ${PROJECT_NAME}_doc_${f})
+endforeach()
+
 # ---------------------------------
 # Top Sphinx target
 # ---------------------------------
-# Sources
-file(GLOB_RECURSE sources *.rst)
+if(NOT DEFINED SPHINXBUILD_EXECUTABLE)
+  find_package(Sphinx)
+endif()
 
-# create documentation target
-set(sphinx_top ${CMAKE_CURRENT_BINARY_DIR}/html/index.html)
-add_custom_command(OUTPUT ${sphinx_top} DEPENDS ${sources}
-  		   COMMAND ${TRIQS_SPHINXBUILD_EXECUTABLE} -c . -j8 -b html ${CMAKE_CURRENT_SOURCE_DIR} html)
-add_custom_target(doc_sphinx ALL DEPENDS ${sphinx_top} ${CMAKE_CURRENT_BINARY_DIR})
+# Sphinx has internal caching, always run it
+add_custom_target(${PROJECT_NAME}_docs_sphinx ALL)
+add_custom_command(
+  TARGET ${PROJECT_NAME}_docs_sphinx
+  COMMAND PYTHONPATH=${PROJECT_BINARY_DIR}/python:$ENV{PYTHONPATH} ${SPHINXBUILD_EXECUTABLE} -j auto -c . -b html ${CMAKE_CURRENT_SOURCE_DIR} html
+)
+
+option(Sphinx_Only "When building the documentation, skip the Python Modules and the generation of C++ Api and example outputs" OFF)
+if(NOT Sphinx_Only)
+  # Autodoc usage requires the python modules to be built first
+  get_property(CPP2PY_MODULES_LIST GLOBAL PROPERTY CPP2PY_MODULES_LIST)
+  if(CPP2PY_MODULES_LIST)
+    add_dependencies(${PROJECT_NAME}_docs_sphinx ${CPP2PY_MODULES_LIST})
+  endif()
+
+  # Generation of C++ Api and Example Outputs
+  add_dependencies(${PROJECT_NAME}_docs_sphinx ${PROJECT_NAME}_docs_cpp2rst ${PROJECT_NAME}_docs_example_output)
+endif()
 
 # ---------------------------------
 # Install
 # ---------------------------------
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ COMPONENT documentation DESTINATION share/doc/triqs_dft_tools
- FILES_MATCHING
- REGEX "\\.(html|pdf|png|gif|jpg|js|xsl|css|py|txt|inv|bib)$"
- PATTERN "_*"
- )
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ COMPONENT documentation DESTINATION share/doc/${PROJECT_NAME}
+  FILES_MATCHING
+  REGEX "\\.(html|pdf|png|gif|jpg|svg|js|xsl|css|py|txt|inv|bib|ttf|woff2|eot)$"
+  PATTERN "_*"
+)

doc/ChangeLog.md

@@ -1,5 +1,142 @@
-Version 2.2.x
--------------
+(changelog)=
+
+# Changelog
+
+## Version 3.1.0
+
+DFTTools Version 3.1.0 is a release that
+* is compatible with TRIQS 3.1.x
+* includes a major update for the Wannier90 converter (see below for details)
+* updates sumk_dft to allow for charge self-consistent DFT+DMFT calculations with Quantum Espresso (dm_type = 'qe')
+* adds a indmftpr helper script to prepare the case.indmftpr file for the dmftproj program
+* uses the latest [app4triqs/3.1.x](https://github.com/TRIQS/app4triqs) skeleton
+
+### Wannier90 Converter
+* allow for charge self-consistent DFT+DMFT calculations
+* spin-orbit coupling implemented
+* option to add a local spin-orbit term to t2g local Hamiltonian (for now just for a single impurity. Fixed in next version)
+* additional choices and added checks for different bases (rot_mat): hloc_diag, wannier (already implemented previously), none
+* code restructured, more tests
+* MPI speedup of the Fourier transform
+* added new test in w90_convert.py for rot_mat_type='hloc_diag'
+* update documentation of W90 Converter
+* bugfix: This fix makes the function find_rot_mat() safer to use in case there are errors in finding the correct mapping. The converter will now abort if the agreement in mapping is below a user-definable threshold.
+
+### Change in gf_struct
+* In line with TRIQS 3.1.x, the form of the Green's function's structure (`gf_struct`) has been modified (see [triqs changelog](https://triqs.github.io/triqs/latest/ChangeLog.html#change-in-gf-struct-objects) for more information)
+* Instead of `gf_struct = [("up", [0, 1]), ("down", [0, 1])]`, the new convention uses `gf_struct = [("up", 2), ("down", 2)]`
+* This modifies the form of `gf_struct_solver` (and `sumk`) in `block_structure` and `SumkDFT` as well.
+* Backwards-compatibility with old, stored `block_structure` objects is given, however a warning is issued.
+* A helper-function `triqs.gf.block_gf.fix_gf_struct_type(gf_struct_old)` is provided in triqs to manually bring `gf_struct`s to the new form.
+
+### Documentation
+* change to read the docs sphinx theme
+* clean up various doc files
+* use autosummary to build reference documentation
+* update Vasp tutorials
+* update Wannier90 documentation to reflect new features
+
+### Cmake
+* require triqs3.1+ in debian package dependencies
+* bump required TRIQS Version to 3.1
+
+### Other changes
+* bugfix for analyse_block_structure in sumk_dft
+* bugfix in blockstructure module for the case of #corr_shells != #ineq_shells
+* fix float comparison tolerances and few minor things in tests
+* Vasp Converter: fixed normalization of kwghts to allow symmetries 
+* bugfix in Elk converter when creating the symmetry matrices of low symmetry systems with multiple equivalent atoms
+* vectorize various loops in dfttools
+* fix various from_L_G_R calls that require now data layed out in C-order
+* use nda over TRIQS_RUNTIME_ERROR in dos_tetra3d
+* changed fermi weights from np array complex to float in accordance with h5 structure
+* expose parameter max_loops in sum_k.calc_mu dichotomy
+
+Thanks to all commit-contributors (in alphabetical order): Sophie Beck, Alexander Hampel, Alyn James, Jonathan Karp, Harry LaBollita, Max Merkel, H. L. Nourse, Hermann Schnait, Nils Wentzell,  @70akaline
+
+
+## Version 3.0.0
+
+DFTTools Version 3.0.0 is a major release that
+
+* is compatible with TRIQS versions 3.0.x
+* introduces compatibility with Python 3 (Python 2 is no longer supported)
+* is now aligned with the general [app4triqs](https://github.com/TRIQS/app4triqs) application skeleton
+* brings a major rework of the VASP interface, including thorough documentation, tutorials, a new Hamiltonian mode, the option to select bands instead of an energy window, and many small bugfixes.
+* brings a major update of the block structure functionalities especially for SOC calculations, with detailed documentation and tutorials. Allows more control over the block structure coming from DFT, cutting out certain orbitals or throwing away off-diagonal elements when preparing input for the solver.
+* New option in dmftproj to select the projection window using band indices instead of energie
+
+### Restructuring
+
+To be aligned with other applications for TRIQS, various files and folders had to be moved to new locations. The c++, fortran and python parts all are now in separate folders. The converter files have been more logically split into their own folders and name spaces. For example the Vasp converter is now located under `python/triqs_dft_tools/converters/vasp.py`. Especially the test folder structure was adapted to fit to the app4triqs skeleton, which separate folders for C++ and python tests.
+
+### Dependency Management
+
+We are managing the interdependencies of the various library components of triqs now using cmake.
+Per default cmake will pull those dependencies from their corresponding
+GitHub repositories, build them, and install these components together
+with TRIQS, unless they are found in your system.
+This behavior can be altered using the additional cmake options
+
+* `-DBuild_Deps="Always"` - Always build dependencies, do not try to find them
+* `-DBuild_Deps="Never"` - Never build dependencies, but find them instead
+
+during the configuration step. See also the TRIQS documentation for more detailed instructions.
+
+### Other Changes:
+
+* Run port_to_triqs3 script
+* Port py files to python3
+* Update triqs python module name
+* synchronize dfttools with app4triqs structure
+* rename all h5 test archives according to test_name.ref.h5
+* Changed 'orb' parameter to 'ish' for consistency in function summ_deg_gf in file sumk_dft.py
+* small fix to read_inp_from_h5 function of Sumk
+* renamed converters from app_converter.py to app.py
+* look at the mesh of each shell of Sigma_imp, not just the first shell
+* add function to find min and max of band energy, and add warning to set_Sigma if its mesh is smaller than the energy bounds
+* warning for set_Sigma if ReFreqMesh is too small
+* fixed a index bug that produced empty projectors for a unit cells with multiple shells in the VASP converter
+* fixed a slicing bug for the calculation of the target density in the VASP converter, which selected 1 band less in the correlated window than required.
+* added printout of complex part of local Hamiltonian in the Vasp converter
+* doc on automatic basis rotations
+* Bugfix in calculate_density_matrix for purely imaginary off-diagonals
+* revamping the VASP interface documentation. Rewrote the interface with VASP guide. Removed the unused in doc/vasp. Start for SVO VASP tutorial as ipynb
+* changed ref file for block structure test, since the order in dicts is not guaranteed the test failed as the order in py3 changed
+* Vasp Converter: efermi is now read from LOCPROJ if DOSCAR does not contain it yet
+* E-Fermi is read from DOSCAR not from LOCPROJ
+* Added Tutorial for basis rotations: Sr2MgOsO6 w/o SOC
+* Vasp converter add kpts and kpts_basis to h5
+* many adjustments to Block structure and rotations including option to throw away certain parts of BlockGf
+* implemented multiple ncsf VASP cycles
+* Ignore imaginary part of the density when calculating mu
+* Adjust hdf5 usage to changes in triqs
+* Calculate diagonalization in solver blocks
+* Do not use deprecated set_from_inverse_fourier
+* add SOC tutorial
+* add Block structure tutorial
+* adding detailed Vasp tutorial
+* Vasp converter now supports Hamiltonian mode
+* Move setup files into separate bash scripts and adjust README
+* Update README file with more detailed instructions
+
+
+Thanks to all commit-contributors (in alphabetical order):
+Markus Aichhorn, Alexander Hampel, Gernot Kraberger, Oleg Peil, Hermann Schnait, Malte Schueler, Nils Wentzell, Manuel Zingl
+
+
+## Version 2.2.1
+
+DFTTools Version 2.2.1 makes the application available
+through the Anaconda package manager. We adjust
+the install pages of the documentation accordingly.
+We provide a more detailed description of the changes below.
+
+* Add a section on the Anaconda package to the install page
+* Add a LICENSE and AUTHORS file to the repository
+
+
+## Version 2.2.0
 
 * Ensure that the chemical potential calculations results in a real number
 * Fix a bug in reading Wien2k optics files in SO/SP cases
@@ -9,13 +146,12 @@ Version 2.2.x
 This is to a large extend a compatibility release against TRIQS version 2.2.0
 
 Thanks to all commit-contributors (in alphabetical order):
-Markus Aichhorn, Dylan Simon, Erik van Loon, Nils Wentzell, Manuel Zingl 
+Markus Aichhorn, Dylan Simon, Erik van Loon, Nils Wentzell, Manuel Zingl
 
 
-Version 2.1.x (changes since 1.4)
----------------------------------
+## Version 2.1.x (changes since 1.4)
 
-* Added Debian Packaging 
+* Added Debian Packaging
 * Compatibility changes for TRIQS 2.1.x
 * Jenkins adjustments
 * Add option to measure python test coverage
@@ -30,4 +166,4 @@ Version 2.1.x (changes since 1.4)
 Thanks to all commit-contributors (in alphabetical order):
 Markus Aichhorn, Gernot J. Kraberger, Olivier Parcollet, Oleg Peil, Hiroshi Shinaoka, Dylan Simon, Hugo U. R. Strand, Nils Wentzell, Manuel Zingl
 
-Thanks to all user for reporting issues and suggesting improvements. 
+Thanks to all user for reporting issues and suggesting improvements.

doc/_static/css/custom.css

@@ -0,0 +1,5 @@
+@import url("theme.css");
+
+.wy-nav-content {
+    max-width: 70em;
+}

doc/_templates/autosummary_class_template.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+{% block methods %}
+{% if methods %}
+.. rubric:: {{ _('Methods') }}
+
+.. autosummary::
+    :toctree:                             
+    {% for item in methods %}
+      ~{{ name }}.{{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+.. rubric:: {{ _('Attributes') }}
+
+.. autosummary::
+    :toctree:                             
+    {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}

doc/_templates/autosummary_module_template.rst

@@ -0,0 +1,68 @@
+{{ name | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+{% block functions %}
+{% if functions %}
+.. rubric:: Functions
+
+.. autosummary::
+    :toctree:                             
+    {% for item in functions %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+.. rubric:: Module Attributes
+
+.. autosummary::
+    :toctree:                             
+    {% for item in attributes %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block classes %}
+{% if classes %}
+.. rubric:: {{ _('Classes') }}
+
+.. autosummary::
+    :toctree:                                         
+    :template: autosummary_class_template.rst
+    {% for item in classes %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block exceptions %}
+{% if exceptions %}
+.. rubric:: {{ _('Exceptions') }}
+
+.. autosummary::
+    :toctree:                                       
+    {% for item in exceptions %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+    :toctree:
+    :template: autosummary_module_template.rst 
+    :recursive:
+
+    {% for item in modules %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+

doc/about.rst

@@ -1,3 +1,8 @@
+.. _about:
+
+About
+******
+
 License
 =======
 
@@ -17,7 +22,7 @@ of full charge self-consistency [#dft_tools2]_, necessary for total energy
 calculations. The package at hand is fully implemented as an application
 based on the TRIQS library [#dft_tools3]_.
 
-**Developers**: M. Aichhorn, L. Pourovskii, P.Seth, V. Vildosola, M. Zingl, O. E. Peil, X. Deng, J. Mravlje, G. Kraberger, C. Martins, M. Ferrero, O. Parcollet
+**Developers**: M. Aichhorn, L. Pourovskii, A. Hampel, P.Seth, V. Vildosola, M. Zingl, O. E. Peil, X. Deng, J. Mravlje, G. Kraberger, A. James, C. Martins, M. Ferrero, O. Parcollet
 
 **Related papers**:
 

doc/changelog.rst

@@ -1,8 +0,0 @@
-.. _changelog:
-
-Changelog
-=========
-
-This document describes the main changes in DFTTools.
-
-.. include:: ChangeLog.md

doc/conf.py.in

@@ -3,41 +3,134 @@
 # TRIQS documentation build configuration file
 
 import sys
-sys.path.insert(0, "@TRIQS_SPHINXEXT_PATH@/numpydoc")
+sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext")
+sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext/numpydoc")
 sys.path.insert(0, "@CMAKE_BINARY_DIR@/python")
 
+# exclude these folders from scanning by sphinx
+exclude_patterns = ['_templates']
+
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.mathjax',
               'sphinx.ext.intersphinx',
-              'matplotlib.sphinxext.plot_directive',
               'sphinx.ext.doctest',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode',
               'sphinx.ext.autosummary',
+              'sphinx.ext.githubpages',
+              'sphinx_autorun',
+              'nbsphinx',
+              'myst_parser',
+              'matplotlib.sphinxext.plot_directive',
+              'nbsphinx',
+              'IPython.sphinxext.ipython_console_highlighting',
               'numpydoc']
 
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "substitution",
+    "tasklist",
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
 source_suffix = '.rst'
 
-project = u'TRIQS DFTTools'
-copyright = u'2011-2019'
-version = '@DFT_TOOLS_VERSION@'
+# Turn on sphinx.ext.autosummary
+autosummary_generate = True
+autosummary_imported_members=False
 
-mathjax_path = "@TRIQS_MATHJAX_PATH@/MathJax.js?config=default"
-templates_path = ['@CMAKE_SOURCE_DIR@/doc/_templates']
+project = 'TRIQS DFTTools'
+version = '@PROJECT_VERSION@'
+
+copyright = '2011-2021'
+
+mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=default"
+templates_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_templates']
+
+# this requires the sphinx_rtd_theme to be installed via pip
+html_theme = 'sphinx_rtd_theme'
+# this loads the custom css file to change the page width
+html_style = 'css/custom.css'
+
+#html_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/logos/favicon.ico'
+#html_logo = '@CMAKE_CURRENT_SOURCE_DIR@/logos/logo.png'
+
+# options for the the rtd theme
+html_theme_options = {
+    'logo_only': False,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    'vcs_pageview_mode': '',
+    'style_nav_header_background': '#7E588A',
+    # Toc options
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
 
-html_theme = 'triqs'
-html_theme_path = ['@TRIQS_THEMES_PATH@']
 html_show_sphinx = False
-html_context = {'header_title': 'dft tools',
-                'header_subtitle': 'connecting <a class="triqs" style="font-size: 12px" href="http://triqs.github.io/triqs">TRIQS</a> to DFT packages',
-                'header_links': [['Install', 'install'],
-                                 ['Documentation', 'documentation'],
-                                 ['Tutorials', 'tutorials'],
-                                 ['Issues', 'issues'],
-                                 ['About DFTTools', 'about']]}
-html_static_path = ['@CMAKE_SOURCE_DIR@/doc/_static']
+
+html_context = {'header_title': 'TRIQS DFTTools'}
+
+html_static_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_static']
 html_sidebars = {'index': ['sideb.html', 'searchbox.html']}
 
-htmlhelp_basename = 'TRIQSDFTToolsdoc'
+htmlhelp_basename = '@PROJECT_NAME@doc'
 
-intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None), 'triqslibs': ('http://triqs.github.io/triqs/master', None), 'triqscthyb': ('https://triqs.github.io/cthyb/master', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3.8', None), 'triqslibs': ('https://triqs.github.io/triqs/latest', None)}
+
+# open links in new tab instead of same window
+from sphinx.writers.html import HTMLTranslator
+from docutils import nodes
+from docutils.nodes import Element
+
+class PatchedHTMLTranslator(HTMLTranslator):
+
+    def visit_reference(self, node: Element) -> None:
+        atts = {'class': 'reference'}
+        if node.get('internal') or 'refuri' not in node:
+            atts['class'] += ' internal'
+        else:
+            atts['class'] += ' external'
+            # ---------------------------------------------------------
+            # Customize behavior (open in new tab, secure linking site)
+            atts['target'] = '_blank'
+            atts['rel'] = 'noopener noreferrer'
+            # ---------------------------------------------------------
+        if 'refuri' in node:
+            atts['href'] = node['refuri'] or '#'
+            if self.settings.cloak_email_addresses and atts['href'].startswith('mailto:'):
+                atts['href'] = self.cloak_mailto(atts['href'])
+                self.in_mailto = True
+        else:
+            assert 'refid' in node, \
+                   'References must have "refuri" or "refid" attribute.'
+            atts['href'] = '#' + node['refid']
+        if not isinstance(node.parent, nodes.TextElement):
+            assert len(node) == 1 and isinstance(node[0], nodes.image)
+            atts['class'] += ' image-reference'
+        if 'reftitle' in node:
+            atts['title'] = node['reftitle']
+        if 'target' in node:
+            atts['target'] = node['target']
+        self.body.append(self.starttag(node, 'a', '', **atts))
+ 
+        if node.get('secnumber'):
+            self.body.append(('%s' + self.secnumber_suffix) %
+                             '.'.join(map(str, node['secnumber'])))
+
+def setup(app):
+    app.set_translator('html', PatchedHTMLTranslator)

doc/contents.rst

@@ -1,12 +0,0 @@
-Table of contents
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   index
-   install
-   documentation
-   issues
-   changelog
-   about

doc/documentation.rst

@@ -9,7 +9,7 @@ Basic notions
 -------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    basicnotions/first
    basicnotions/dft_dmft
@@ -23,6 +23,7 @@ Construction of local orbitals from DFT
    :maxdepth: 2
 
    guide/conversion
+   h5structure
 
 
 DFT+DMFT
@@ -34,11 +35,21 @@ DFT+DMFT
    guide/dftdmft_singleshot
    guide/dftdmft_selfcons
 
+Advanced Topics
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   guide/blockstructure
+   guide/BasisRotation
+   guide/soc
+
 Postprocessing
 --------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    guide/analysis
    guide/transport
@@ -49,16 +60,18 @@ Reference manual
 
 This is the reference manual for the python routines.
 
-.. toctree::
-   :maxdepth: 2
+.. autosummary::
+   :recursive:
+   :toctree: _python_api
+   :template: autosummary_module_template.rst
+
+   block_structure
+   converters
+   sumk_dft
+   sumk_dft_tools
+   symmetry
+   trans_basis
 
-   reference/h5structure
-   reference/converters
-   reference/sumk_dft
-   reference/sumk_dft_tools
-   reference/symmetry
-   reference/transbasis
-   reference/block_structure
 
 
 FAQs

doc/guide/BasisRotation.rst

@@ -0,0 +1,82 @@
+.. _basisrotation:
+
+Automatic basis rotations in DFT+DMFT
+=====================================
+
+When performing calculations with off-diagonal terms in the hybridisation function or in the local Hamiltonian, one is
+often limited by the fermionic sign-problem slowing down the QMC calculations significantly. This can occur for instance if the crystal shows locally rotated or distorted cages, or when spin-orbit coupling is included. The examples for this are included in the :ref:`tutorials` of this documentation.
+
+However, as the fermonic sign in the QMC calculation is no
+physical observable, one can try to improve the calculation by rotating
+to another basis. While this basis can in principle be chosen arbitrarily, 
+two choices which have shown good results; name the basis sets that diagonalize the local Hamiltonian or the local density matrix of the
+system.
+
+As outlined in section :ref:`blockstructure`, the :class:`BlockStructure` includes all necessary functionalities. While it is possible to manually transform each Green's functions and self energies between the *sumk* and the *solver* basis, this leads to cumbersum code and is discouraged. Instead, in order to facilitate the block-structure manipulations for an actual DFT+DMFT calculation, some of the necessary steps are automatically included automatically. As soon as the 
+transformation matrix is stored in the :class:`BlockStructure`, the
+transformation is automatically performed when using :class:`SumkDFT`'s :meth:`extract_G_loc`,
+:meth:`put_Sigma`, and :meth:`calc_dc` (see below).
+
+Setting up the initial solver structure from DFT
+------------------------------------------------
+
+Before the actual calculation one has to specify the *solver* basis structure, in which the impurity problem will be tackled. The different available approximation were introduced in section :ref:`blockstructure`. An important feature of DFTTools is that there is an automatic way to determine the entries of the Green's function matrix that are zero by symmetry, when initialising the class::
+
+    from triqs_dft_tools.sumk_dft import *
+    SK = SumkDFT(hdf_file,use_dft_blocks='True')
+
+The flag *use_dft_blocks=True* analysis the local density matrix, determines the zero entries, and sets up a minimal *solver* structure. Alternatively, this step can be achieved by (see the reference manual for options)::
+
+    SK.analyse_block_structure()
+
+
+Finding the transformation matrix
+---------------------------------
+
+The SumkDFT class offers a method that can determine transformation matrices to certain new basis. It is called as follows::
+
+    SK.calculate_diagonalization_matrix(prop_to_be_diagonal='eal')
+
+Possible option for *prop_to_be_diagonal* are *eal* (diagonalises the local hamiltonian) or *dm* (diagonalises the local density matrix). This routine stores the transformation matrix in the :class:`SK.block_structure` class, such that it can be used to rotate the basis. 
+
+
+
+Automatic transformation during the DMFT loop
+---------------------------------------------
+
+During a DMFT loop one is often switching back and forth between the unrotated basis (Sumk-Space) and the rotated basis that is used by the QMC Solver.
+Once the SK.block_structure.transformation property is set as shown above, this is
+done automatically, meaning that :class:`SumkDFT`'s :meth:`extract_G_loc`, :meth:`put_Sigma`, and :meth:`calc_dc` are doing the transformations by default::
+
+    for it in range(iteration_offset, iteration_offset + n_iterations):
+        # every GF is in solver space here
+        S.G0_iw << inverse(S.Sigma_iw + inverse(S.G_iw))
+
+        # solve the impurity in solver space -> hopefully better sign
+        S.solve(h_int = H, **p)
+
+        # calc_dc(..., transform = True) by default
+        SK.calc_dc(S.G_iw.density(), U_interact=U, J_hund=J, orb=0, use_dc_formula=DC_type)
+        
+        # put_Sigma(..., transform_to_sumk_blocks = True) by default
+        SK.put_Sigma([S.Sigma_iw])
+        
+        SK.calc_mu()
+
+        # extract_G_loc(..., transform_to_solver_blocks = True) by default
+        S.G_iw << SK.extract_G_loc()[0]
+
+.. warning::
+  Before doing the DMFT self-consistency loop, one must not forget to also transform the 
+  interaction Hamiltonian to the diagonal basis!
+  This can be also be done with a method of the :class:`BlockStructure` class, 
+  namely the :meth:`convert_operator` method. Having set up a Hamiltonian in the *sumk* structure, it can easily 
+  be transformed to the *solver* structure (including rotations of basis, picking of orbitals, 
+  making matrices diagonal, etc) by::
+
+    H_solver = SK.block_structure.convert_operator(H_sumk)
+
+  We refer to the tutorials on how to set up the Hamiltonian H_sumk in selected cases.
+  Note that this transformation might generally lead to complex values in the 
+  interaction Hamiltonian. Unless you know better and can make everything real, 
+  you should take care of using the correct version of the TRIQS CTQMC solver.

doc/guide/Sr2MgOsO6/Sr2MgOsO6.indmftpr

@@ -0,0 +1,21 @@
+5                ! Nsort
+2 1 1 4 2            ! Mult(Nsort)
+3                ! lmax
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+cubic            ! choice of angular harmonics
+0 0 2 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+0                ! SO flag
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+complex
+0 0 0 0
+0 0 0 0
+-0.088 0.43      ! 0.40 gives warnings, 0.043 gives occ 1.996
+0.04301

doc/guide/Sr2MgOsO6/Sr2MgOsO6.struct

@@ -0,0 +1,72 @@
+Sr2MgOsO6                                s-o calc. M||  0.00  0.00  1.00       
+B                            5   87                                            
+             RELA                                                              
+ 10.507954 10.507954 14.968880 90.000000 90.000000 90.000000                   
+ATOM  -1: X=0.00000000 Y=0.50000000 Z=0.75000000
+          MULT= 2          ISPLIT=-2
+      -1: X=0.50000000 Y=0.00000000 Z=0.75000000
+Sr  2+     NPT=  781  R0=.000010000 RMT= 2.50000     Z:  38.00000              
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -2: X=0.00000000 Y=0.00000000 Z=0.00000000
+          MULT= 1          ISPLIT=-2
+Os  6+     NPT=  781  R0=.000005000 RMT= 1.94        Z:  76.00000              
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -3: X=0.00000000 Y=0.00000000 Z=0.50000000
+          MULT= 1          ISPLIT=-2
+Mg  2+     NPT=  781  R0=.000100000 RMT= 1.89        Z:  12.00000              
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -4: X=0.74270000 Y=0.21790000 Z=0.00000000
+          MULT= 4          ISPLIT= 8
+      -4: X=0.25730000 Y=0.78210000 Z=0.00000000
+      -4: X=0.21790000 Y=0.25730000 Z=0.00000000
+      -4: X=0.78210000 Y=0.74270000 Z=0.00000000
+O  2-      NPT=  781  R0=.000100000 RMT= 1.58        Z:   8.00000              
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -5: X=0.00000000 Y=0.00000000 Z=0.75390000
+          MULT= 2          ISPLIT=-2
+      -5: X=0.00000000 Y=0.00000000 Z=0.24610000
+O  2-      NPT=  781  R0=.000100000 RMT= 1.58        Z:   8.00000              
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+   8      NUMBER OF SYMMETRY OPERATIONS
+ 0-1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0-1 0.00000000
+       1
+-1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0-1 0.00000000
+       2
+ 1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0-1 0.00000000
+       3
+ 0-1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0 1 0.00000000
+       4
+ 0 1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0-1 0.00000000
+       5
+-1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0 1 0.00000000
+       6
+ 1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0 1 0.00000000
+       7
+ 0 1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0 1 0.00000000
+       8

doc/guide/Sr2MgOsO6/Sr2MgOsO6_SOC.indmftpr

@@ -0,0 +1,21 @@
+5                ! Nsort
+2 1 1 4 2            ! Mult(Nsort)
+3                ! lmax
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+cubic            ! choice of angular harmonics
+0 0 2 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+1                ! SO flag
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+complex          ! choice of angular harmonics
+0 0 0 0          ! l included for each sort
+0 0 0 0          ! If split into ireps, gives number of ireps. for a given orbital (otherwise 0)
+complex
+0 0 0 0
+0 0 0 0
+-0.088 0.43      ! 0.40 gives warnings, 0.043 gives occ 1.996
+0.04301

doc/guide/Sr2RuO4/Sr2RuO4.indmftpr

@@ -0,0 +1,17 @@
+4 ! Nsort
+2 1 2 2 ! Multiplicities
+3 ! lmax
+complex ! Sr
+0 0 0 0
+0 0 0 0
+cubic ! Ru
+0 0 2 0 ! include d-shell as correlated
+0 0 0 0 ! there are no irreps with SO
+1 ! SO-flag
+complex ! O1
+0 0 0 0
+0 0 0 0
+complex ! O2
+0 0 0 0
+0 0 0 0
+-0.7 1.4 ! energy window (Ry)

doc/guide/Sr2RuO4/Sr2RuO4.struct

@@ -0,0 +1,96 @@
+Sr2RuO4                                  s-o calc. M||  0.00  0.00  1.00
+B                            4 39_I
+             RELA
+  7.300012  7.300012 24.044875 90.000000 90.000000 90.000000
+ATOM  -1: X=0.00000000 Y=0.00000000 Z=0.35240000
+          MULT= 2          ISPLIT=-2
+      -1: X=0.00000000 Y=0.00000000 Z=0.64760000
+Sr2+       NPT=  781  R0=.000010000 RMT=   2.26000   Z:  38.00000
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -2: X=0.00000000 Y=0.00000000 Z=0.00000000
+          MULT= 1          ISPLIT=-2
+Ru4+       NPT=  781  R0=.000010000 RMT=   1.95000   Z:  44.00000
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -3: X=0.50000000 Y=0.00000000 Z=0.00000000
+          MULT= 2          ISPLIT= 8
+      -3: X=0.00000000 Y=0.50000000 Z=0.00000000
+O 2-       NPT=  781  R0=.000100000 RMT=   1.68000   Z:   8.00000
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+ATOM  -4: X=0.00000000 Y=0.00000000 Z=0.16350000
+          MULT= 2          ISPLIT=-2
+      -4: X=0.00000000 Y=0.00000000 Z=0.83650000
+O 2-       NPT=  781  R0=.000100000 RMT=   1.68000   Z:   8.00000
+LOCAL ROT MATRIX:    1.0000000 0.0000000 0.0000000
+                     0.0000000 1.0000000 0.0000000
+                     0.0000000 0.0000000 1.0000000
+  16      NUMBER OF SYMMETRY OPERATIONS
+ 0-1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0-1 0.00000000
+       1   A   2 so. oper.  type  orig. index
+-1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0-1 0.00000000
+       2   A   3
+ 1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0-1 0.00000000
+       3   A   6
+ 0-1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0 1 0.00000000
+       4   A   8
+ 0 1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0-1 0.00000000
+       5   A   9
+-1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0 1 0.00000000
+       6   A  11
+ 1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0 1 0.00000000
+       7   A  14
+ 0 1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0 1 0.00000000
+       8   A  15
+ 1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0-1 0.00000000
+       9   B   1
+ 0 1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0-1 0.00000000
+      10   B   4
+ 0-1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0-1 0.00000000
+      11   B   5
+ 1 0 0 0.00000000
+ 0-1 0 0.00000000
+ 0 0 1 0.00000000
+      12   B   7
+-1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0-1 0.00000000
+      13   B  10
+ 0 1 0 0.00000000
+ 1 0 0 0.00000000
+ 0 0 1 0.00000000
+      14   B  12
+ 0-1 0 0.00000000
+-1 0 0 0.00000000
+ 0 0 1 0.00000000
+      15   B  13
+-1 0 0 0.00000000
+ 0 1 0 0.00000000
+ 0 0 1 0.00000000
+      16   B  16

doc/guide/Sr2RuO4/calculate_dos_wannier_basis.py

@@ -0,0 +1,15 @@
+from triqs_dft_tools.converters.wien2k import Wien2kConverter
+from triqs_dft_tools import SumkDFTTools
+
+filename = 'Sr2RuO4'
+
+conv = Wien2kConverter(filename = filename,hdf_filename=filename+'.h5')
+conv.convert_dft_input()
+
+SK = SumkDFTTools(filename+'.h5')
+mesh = (-10.0,10.0,500)
+SK.dos_wannier_basis(broadening=(mesh[1]-mesh[0])/float(mesh[2]),
+                     mesh=mesh,
+                     save_to_file=True,
+                     with_Sigma=False,
+                     with_dc=False)

doc/guide/analysis.rst

@@ -37,7 +37,7 @@ class::
 Note that all routines available in :class:`SumkDFT <dft.sumk_dft.SumkDFT>` are also available here.
 
 If required, we have to load and initialise the real-frequency self energy. Most conveniently,
-you have your self energy already stored as a real-frequency :class:`BlockGf <pytriqs.gf.BlockGf>` object
+you have your self energy already stored as a real-frequency :class:`BlockGf <triqs.gf.BlockGf>` object
 in a hdf5 file::
 
   with HDFArchive('case.h5', 'r') as ar:
@@ -45,10 +45,10 @@ in a hdf5 file::
 
 You may also have your self energy stored in text files. For this case the :ref:`TRIQS <triqslibs:welcome>` library offers
 the function :meth:`read_gf_from_txt`, which is able to load the data from text files of one Green function block
-into a real-frequency :class:`ReFreqGf <pytriqs.gf.ReFreqGf>` object. Loading each block separately and
-building up a :class:´BlockGf <pytriqs.gf.BlockGf>´ is done with::
+into a real-frequency :class:`ReFreqGf <triqs.gf.ReFreqGf>` object. Loading each block separately and
+building up a :class:´BlockGf <triqs.gf.BlockGf>´ is done with::
 
-  from pytriqs.gf.tools import *
+  from triqs.gf.tools import *
   # get block names
   n_list = [n for n,nl in SK.gf_struct_solver[0].iteritems()]
   # load sigma for each block - in this example sigma is composed of 1x1 blocks
@@ -128,7 +128,7 @@ Momentum resolved spectral function (with real-frequency self energy)
 
 Another quantity of interest is the momentum-resolved spectral function, which can directly be compared to ARPES
 experiments. First we have to execute `lapw1`, `lapw2 -almd` and :program:`dmftproj` with the `-band` 
-option and use the :meth:`convert_bands_input <dft.converters.wien2k_converter.Wien2kConverter.convert_bands_input>`
+option and use the :meth:`convert_bands_input <dft.converters.wien2k.Wien2kConverter.convert_bands_input>`
 routine, which converts the required files (for a more detailed description see :ref:`conversion`). The spectral function is then calculated by typing::
 
   SK.spaghettis(broadening=0.01,plot_shift=0.0,plot_range=None,ishell=None,save_to_file='Akw_')

doc/guide/blockstructure.rst

@@ -0,0 +1,131 @@
+.. _blockstructure:
+
+Manipulating the Green's functions block structure
+==================================================
+
+The DFTTools package includes the general :class:`BlockStructure <dft.block_structure.BlockStructure>` class for manipulating the blocks of Green's functions (see also the TRIQS documentation on BlockGF). In the following, we will introduce its basic and most commonly used functionalities that might show up in an actual DFT+DMFT calculation, and will illustrate them on a very basic fictitious problem.
+
+The main idea is to have two structures for the Greens functions available. The first one is used in the procedures of the :class:`SumkDFT <dft.sumk_dft.SumkDFT>` to calculate Dysons equations, lattice Greens functions, and so on, and is normally a full matrix. For instance, in a calculation using :math:`t_{2g}` orbitals without spin-orbit-coupling, you have an spin-up block of size 3x3 and a spin-down block of the same size. In the following, wee will refer to this structure as *sumk* structure. 
+
+The second structure, called *solver* structure, is the one which is used for the solution of the Anderson impurity problem. As a matter of fact, in particular in combination with quantum Monte Carlo techniques, it is advisable to use as small blocks as possible in order to run into numerical problems. In particular, it should contain information about the symmetry of the local problem.
+
+Creating a block structure and Green's function
+-----------------------------------------------
+
+For the purpose of this documentation, we focus on an example of a 3x3 Green's function, consisting of a 1x1 block and a 2x2 block (with off-diagonal coupling). This is reminiscent of a :math:`t_{2g}` manifold. Note that this initialisation is normally done automatically by DFTTools, we do it here manually for demonstration purposes only.
+
+We can create a simple :class:`BlockStructure <dft.block_structure.BlockStructure>` object as follows::
+    
+    from triqs_dft_tools import BlockStructure
+    BS = BlockStructure.full_structure([{'up':[0,1,2]}], None)
+
+This creates a block structure with one 3x3 block named *up*. Note that we have not created any Green's function yet; this is just the structure of those objects. If you want to create a Green's function with this structure, you can do (we will if with some content also)::
+
+    from triqs.gf import *
+    GF_sumk = BS.create_gf(space='sumk', beta = 40, n_points = 1000)
+    GF_sumk['up'][0,0] << iOmega_n - 2.0
+    GF_sumk['up'][1,1] << iOmega_n + 0.5
+    GF_sumk['up'][2,2] << iOmega_n + 0.5
+    GF_sumk['up'][1,2] << 0.1
+    GF_sumk['up'][2,1] << 0.1
+    GF_sumk['up'] << inverse(GF_sumk['up'])
+
+Technically, we use the *sumk* block structure for this Green's function. However, at this point, sumk and solver structure are still the same.
+
+A plot of this structure looks like this. Note that there are off-diagonal elements which are exactly zero by construction.
+
+.. image:: images_scripts/BS_GFsumk.png
+    :width: 600
+    :align: center
+
+The *solver* structure
+----------------------
+
+The method:`BlockStructure.full_structure()` method, as we used it above to create our BlockStructure object, yields - as the name suggests - a full structure, where *sumk* and *solver* structure are identical. Now we want to take advantage of the symmetries of the problem to reduce the *solver* block structure to the relevant matrix elements only. In our case the [0,0] matrix element of the Green's function is completely decoupled from the 2x2 matrix of [1:2,1:2] elements. We simplify the *solver* structure by setting the mapping of each orbital to its target block and orbital::
+
+    BS.map_gf_struct_solver([{('up',0):('up_0',0), ('up',1):('up_1',0), ('up',2):('up_1',1)}])
+
+This creates a *solver* structure different from the *sumk* structure. To see the result, let us look at the Green's function in the *solver* structure now::
+
+    GF_solver = BS.convert_gf(GF_sumk, space_from='sumk', space_to='solver')
+
+This converts the GF_sumk into GF_solver, which looks like this.
+
+.. image:: images_scripts/BS_GF_up_0.png
+    :width: 200
+    :align: center
+
+.. image:: images_scripts/BS_GF_up_1.png
+    :width: 400
+    :align: center
+
+As you can see, the Green's function in the *solver* structure now consists of two blocks: one 1x1 block (called *up_0*) and one 2x2 block (called *up_1*). This is no approximation, as the off-diagonal elements between these blocks are exactly zero anyway.
+
+Picking orbitals
+----------------
+
+In some cases it might happen that for the projection to localised orbitals a full *d* or *f*-shell has to be used. However, for the Anderson impurity problem, just a subset of the orbitals are needed. This is the case, e.g., when the projection leads to completely empty or full orbitals that you don't want to include in the AIM. 
+
+For the example here, the local energy of the *up_0* block (2 eV) is higher than that of the *up_1* block (0.4 and 0.6 eV). Assuming that the chemical potential lies somewhere in the range of the *up_1* block, we might restrict our calculation to only this *up_1* block. The :class:`BlockStructure <dft.block_structure.BlockStructure>` class includes methods to pick a subset or orbitals::
+
+    BS.pick_gf_struct_solver([{'up_1':[0,1]}])
+    GF2 = BS.convert_gf(GF_sumk, space_from='sumk', space_to='solver')
+
+Now the Green's function GF2 consists of only one 2x2 block, called *up_1*, as we have left out the *up_0* block.
+
+Basis rotations
+---------------
+
+In cases where the Greens function or the local Hamiltonian shows off diagonal entries in the chosen basis, it is often beneficial to rotate to a different basis. This is of particular interest when using a QMC solver, since off-diagonal contributions lead to a famous fermionic sign problem. The :class:`BlockStructure <dft.block_structure.BlockStructure>` class includes methods to perform such basis rotations.
+
+In our example, the local Hamiltonian is given by
+
+.. math::
+
+    \varepsilon_{mm'} = \begin{pmatrix} 2.0 & 0.0 & 0.0 \\0.0  & -0.5 & -0.1\\0.0 & -0.1 & -0.5 \end{pmatrix}
+
+It is easy to check that the following matrix diagonalises this local Hamiltonian:
+
+.. math::
+
+    T_{mm'} = \begin{pmatrix} 1.0 & 0.0 & 0.0 \\0.0  & 1/\sqrt{2} & -1/\sqrt{2}\\0.0 & 1/\sqrt{2} & 1/\sqrt{2} \end{pmatrix}
+
+With this unitary matrix, we can do a basis rotation to reduce the size of the off-diagonal matrix elements. Note that the transformation matrix has to be given in the *sumk* basis form (a 3x3 matrix in this case)::
+
+    import numpy as np
+    # Unitary transformation matrix
+    T = np.array([[1,0,0],[0,1./np.sqrt(2),-1./np.sqrt(2)],[0,1./np.sqrt(2),1./np.sqrt(2)]])
+
+    BS.transformation = [T]
+    GF3 = BS.convert_gf(GF_sumk, space_from='sumk', space_to='solver')
+
+.. image:: images_scripts/BS_GF_up_1_rotated.png
+    :width: 400
+    :align: center
+
+As you can see, the offdiagonal elements are reduced to 1e-16 in this basis. Please note that our example is not the most generic case. Normally, due to non-local hybridisation, the off-diagonals can be made smaller, but not exactly zero.
+
+Diagonal approximation
+----------------------
+
+As said above, off diagonal contributions lead to some troubles. However,
+when you are exactly sure that you know what you are doing, there is functionality to take only the diagonal parts into account in the block structure. Be careful, there is no automatic check whether this approximation is justified or not!
+
+Starting from the rotated basis as done above, we can get rid of the off-diagonals as follows::
+
+    BS.approximate_as_diagonal()
+    GF4 = BS.convert_gf(GF_sumk, space_from='sumk', space_to='solver')
+
+The Green's function GF4 consists now only of two 1x1 blocks, where *up_1* was the [0,0] element of the former 2x2 block, and *up_2* was the [1,1] element:
+
+.. image:: images_scripts/BS_GF_up_1_rotated_diag.png
+    :width: 200
+    :align: center
+
+.. image:: images_scripts/BS_GF_up_2_rotated_diag.png
+    :width: 200
+    :align: center
+
+In summary, we started with a full 3x3 matrix in the very beginning, and ended with two 1x1 blocks containing the relevant matrix elements for the calculation.
+
+  

doc/guide/conv_W90.rst

@@ -1,30 +1,36 @@
 .. _convW90:
 
-Wannier90 Converter
-===================
+Interface with Wannier90
+========================
 
-Using this converter it is possible to convert the output of
-`wannier90 <http://wannier.org>`_
-Maximally Localized Wannier Functions (MLWF) and create a HDF5 archive
-suitable for one-shot DMFT calculations with the
-:class:`SumkDFT <dft.sumk_dft.SumkDFT>` class.
+This interface allows to convert the output of `wannier90 <http://wannier.org>`_
+Maximally Localized Wannier Functions (MLWF) and create a HDF5 archive suitable for DMFT calculations with the
+:class:`SumkDFT <dft.sumk_dft.SumkDFT>` class. The tasks are parallelized with MPI.
 
-The user must supply two files in order to run the Wannier90 Converter:
+The converter can be run in two different modes, which are specified with the keyword ``bloch_basis`` in the call::
+
+    from triqs_dft_tools.converters import Wannier90Converter
+    Converter = Wannier90Converter(seedname='seedname', bloch_basis=False, rot_mat_type='hloc_diag', add_lambda=None)
+
+Here and in the following, the keyword ``seedname`` should always be intended
+as a placeholder for the actual prefix chosen by the user when creating the
+input for :program:`wannier90`.
+
+Orbital mode
+---------------
+
+In the default mode (``bloch_basis = False``), the Converter writes the Hamiltonian in orbital basis, in which case
+the projector functions are trivial identity matrices. The user must supply two files:
 
 #. The file :file:`seedname_hr.dat`, which contains the DFT Hamiltonian
-   in the MLWF basis calculated through :program:`wannier90` with ``hr_plot = true``
+   in the MLWF basis calculated through :program:`wannier90` with ``write_hr = true``
    (please refer to the :program:`wannier90` documentation).
 #. A file named :file:`seedname.inp`, which contains the required
    information about the :math:`\mathbf{k}`-point mesh, the electron density,
    the correlated shell structure, ... (see below).
 
-Here and in the following, the keyword ``seedname`` should always be intended
-as a placeholder for the actual prefix chosen by the user when creating the
-input for :program:`wannier90`.
 Once these two files are available, one can use the converter as follows::
 
-    from triqs_dft_tools.converters import Wannier90Converter
-    Converter = Wannier90Converter(seedname='seedname')
     Converter.convert_dft_input()
 
 The converter input :file:`seedname.inp` is a simple text file with
@@ -84,13 +90,57 @@ In our `Pnma`-LaVO\ :sub:`3` example, for instance, we could use::
 where the ``x=-1,1,0`` option indicates that the V--O bonds in the octahedra are
 rotated by (approximatively) 45 degrees with respect to the axes of the `Pbnm` cell.
 
+The last line of :file:`seedname.inp` is the DFT Fermi energy (in eV), which is subtracted from the onsite
+terms in the :file:`seedname_hr.dat` file. This is recommended since some functions in DFTTools implicitly
+assume a Fermi energy of 0 eV. 
+
+In the orbital mode the Converter supports the addition of a local spin-orbit term, if the Wannier Hamiltonian
+describes a t\ :sub:`2g` manifold. Currently, the correct interaction term is only implemented if the default
+orbital order of :program:`wannier90` is maintained, i.e. it is assumed to be
+:math:`d_{xz,\uparrow}, d_{yz,\uparrow}, d_{xy,\uparrow}, d_{xz,\downarrow}, d_{yz,\downarrow}, d_{xy,\downarrow}`.
+The coupling strength can be specified as ``add_lambda = [lambda_x, lambda_y, lambda_z]``,
+representative of the orbital coupling terms perpendicular to :math:`[x, y, z]` i.e. :math:`[d_{yz}, d_{xz}, d_{xy}]`,
+respectively. Note that it is required to have ``SO=0`` and ``SP=1``.
+
+Band mode
+----------------
+
+If ``bloch_basis = True``, the Converter writes the Hamiltonian in the Kohn-Sham basis that was used to construct
+the Wannier functions. The projector functions are then given by the transformation from Kohn-Sham to orbital basis.
+Note that to do so :program:`wannier90` must be run with ``write_u_matrices = true``. Additionally to the files
+described above, the Converter will require the following files:
+
+#. :file:`seedname_u.mat` (and :file:`seedname_u_dis.mat` if disentanglement was used to construct the Wannier functions.) is read to construct the projector functions.
+#. :file:`seedname.eig` is read to get the Kohn-Sham band eigenvalues
+#. :file:`seedname.nnkp` is read to obtain the band indices of the orbitals selected for the Wannier Hamiltonian
+#. :file:`seedname.wout` is read to get the outer energy window to ensure the correct mapping of the disentanglement
+
+Note that in case of disentanglement the user must set the outer energy window (``dis_win_min`` and ``dis_win_max``) explicitly in :program:`wannier90` with an energy
+separation of at least :math:`10^{-4}` to the band energies. This means in particular that one should not use the default energy window to avoid subtle bugs.
+
+Additionally, to keep the dimension of the lattice Green's function reasonable, it is recommendable to use the exclude_bands tag for bands completely outside of the energy window.
+
+The Converter currently works with Quantum Espresso and VASP. Additional files are required for each case to obtain
+the Fermi weights:
+
+#. :file:`seedname.nscf.out` for Quantum Espresso (the NSCF run must contain the flag ``verbosity = 'high'``)
+#. :file:`OUTCAR` and :file:`LOCPROJ` for VASP
+
+Note that in the band mode the user input of the :math:`k`-mesh and the Fermi energy in :file:`seedname.inp` are ignored, since both quantities
+are automatically read from the :program:`wannier90` and DFT output. However, the :math:`k`-mesh parameter still has to be specified to comply with the file format.
+
+Rotation matrix
+------------------
+
 The converter will analyse the matrix elements of the local Hamiltonian
 to find the symmetry matrices `rot_mat` needed for the global-to-local
 transformation of the basis set for correlated orbitals
 (see section :ref:`hdfstructure`).
-The matrices are obtained by finding the unitary transformations that diagonalize
+If ``rot_mat_type='hloc_diag'``, the matrices are obtained by finding the unitary transformations that diagonalize
 :math:`\langle w_i | H_I(\mathbf{R}=0,0,0) | w_j \rangle`, where :math:`I` runs
 over the correlated shells and `i,j` belong to the same shell (more details elsewhere...).
+If ``rot_mat_type='wannier'``, the matrix for the first correlated shell per impurity will be identity, defining the reference frame,
+while the rotation matrices of all other equivalent shells contain the correct mapping into this reference frame.
 If two correlated shells are defined as equivalent in :file:`seedname.inp`,
 then the corresponding eigenvalues have to match within a threshold of 10\ :sup:`-5`,
 otherwise the converter will produce an error/warning.
@@ -98,20 +148,17 @@ If this happens, please carefully check your data in :file:`seedname_hr.dat`.
 This method might fail in non-trivial cases (i.e., more than one correlated
 shell is present) when there are some degenerate eigenvalues:
 so far tests have not shown any issue, but one must be careful in those cases
-(the converter will print a warning message).
+(the converter will print a warning message and turns off the use of rotation matrices,
+which leads to an incorrect mapping between equivalent correlated shells).
+
+Current limitations
+----------------------------------------------
 
 The current implementation of the Wannier90 Converter has some limitations:
 
 * Since :program:`wannier90` does not make use of symmetries (symmetry-reduction
   of the :math:`\mathbf{k}`-point grid is not possible), the converter always
   sets ``symm_op=0`` (see the :ref:`hdfstructure` section).
-* No charge self-consistency possible at the moment.
-* Calculations with spin-orbit (``SO=1``) are not supported.
 * The spin-polarized case (``SP=1``) is not yet tested.
-* The post-processing routines in the module
-  :class:`SumkDFTTools <dft.sumk_dft_tools.SumkDFTTools>`
-  were not tested with this converter.
 * ``proj_mat_all`` are not used, so there are no projectors onto the
   uncorrelated orbitals for now.
-
-

doc/guide/conv_elk.rst

@@ -0,0 +1,203 @@
+.. _convElk:
+
+Interface with Elk
+=====================
+
+This is the first iteration of the Elk-TRIQS interface, so certain inputs may change in later updates. The Elk part of the interface is not currently in the main distribution, but it can be found `here <https://github.com/AlynJ/Elk_interface-TRIQS>`_.
+
+We assume that the user has obtained a self-consistent solution of the
+Kohn-Sham equations with Elk (a full tutorial can be found here :ref:`Elk SVO tutorial <SrVO3_elk>`). Also, the user needs to be familiar with the main in/output files of Elk, and how to run
+the DFT code. Further information about Elk can be found on the `official Elk website <http://elk.sourceforge.net/>`_.
+
+Conversion for the DMFT self-consistency cycle
+----------------------------------------------
+
+Once the user has obtained the groundstate calculation, they will have to rerun Elk but with some small changes to the inputs in the elk.in file which will be explained below. The Elk part of the interface calculates and outputs the Wannier projectors. All downfolding related flags are set in the elk input file, and Elk determines automatically by symmetry equivalent sites. The TRIQS Elk converter then reads in these projectors along with the other Elk ascii files which would have been generated in the Elk ground state calculation. This information is then packed into the HDF5 file.
+
+In the following, we use SrVO3 as an example to explain the flags required in the elk.in input file. An example elk.in of SrVO3 is available in the :ref:`SrVO3 tutorial <SrVO3_elk>`:
+
+.. literalinclude:: ../tutorials/svo_elk/elk.in
+
+
+The projectors are generated in Elk using these alterations in the elk.in file::
+  
+  task
+   805
+
+  wanproj
+   1            !1) number of projector species
+   2 2 3        !2) species number, l value and lm submatrix size
+   7 8 9        !3) cubic harmonic lm indices 
+   -0.055 0.07  !4) Correlated energy window in Hartrees (this is [-1.5, 1.9] in eV)
+
+The first flag "task" specifies Elk to do the Wannier projector calculation in the Elk input convention. The "wanproj" flag specifies the information needed to generate the desired projectors (the exclamation marks are comment flags in Fortran). Below gives the meaning of each line:
+
+#. The number of different species to generate the projectors for. If the material has multiple atoms of the same species, then the projectors will be generated for all of these atoms. Information about whether these atoms are symmetrically equivalent is written to the PROJ.OUT file. Generating projectors for multiple species requires lines 2) and 3) to be repeated for each projector species. 
+#. The desired species index (relative to the order of the "atoms" input in elk.in), the l value and the number of wanted lm orbitals for the projectors. 
+#. The lm indices (in the cubic harmonics by default) where lm = 1 refers to the s orbital, lm = 2,3,4 refers to the p orbitals, lm = 5,6,7,8,9 refers to the d orbitals and finally lm = 10,11,12,13,14,15,16 refers to the f orbitals. In the example above, this specifies that we want the t2g orbitals which has size 3 [last number in line 2)] and the lm indices are 7, 8 and 9 as specified in line 3). If, on the other hand, the user wishes to use all of the d-orbitals then all 5 orbital indices need to be included along with specifying that all 5 orbitals will be used [at the end of line 2)].
+#. The correlated energy window (in Hartree) to generate the projectors within.
+
+It should be noted that the indices in line 3) will change if another lm basis is used. 
+The default is the cubic harmonic basis. The flags in elk.in required to change the spherical harmonic basis are::
+
+  cubic
+   .true.
+
+  lmirep
+   .true.
+
+Above are the default inputs. If both of these flags are set to .false., the projectors will be generated in the complex spherical harmonic basis. It is possible to generate the projectors in Elk's irreducible basis by setting cubic to .false., but this is experimental and the TRIQS side of the interface is 
+currently unable to convert the projectors in that basis. Finally, these projectors are written to file in the complex spherical harmonic basis.
+
+Also, the input flag called "wanind", when set to .true. in elk.in, enables the user to input the lower and upper band indices (respectively) in line 4) of "wanproj" instead of the correlated energy window energies. An example of the inputs in the elk.in file::
+
+  wanind
+   .true.
+
+  wanproj
+   1      !No. of projector species
+   2 2 3  !species, l, lm submatrix size
+   7 8 9  !lm indices
+   21 25  !correlated energy window band indices.
+
+Note that for magnetic systems (spin uncoupled calculations), only the indices of the majority spin bands are used as inputs. The code calculates the indices for the minority spin automatically.
+
+
+.. _Elk_files:
+
+The rest of the elk.in file can remain unchanged. This 805 task calculates the projectors which are written into the WANPROJ_L**_S**_A****.OUT file(s). Note that the projectors will be written in the complex spherical harmonic basis. Along with this, the other written file (PROJ.OUT) specficies some information about the projectors (like atom equivalency, lm indices and so on) needed for reading the files into the TRIQS library. The PROJ.OUT file contains comments about its outputs. Here's a list of all of the input files needed for this part of the TRIQS converter:
+
+#. WANPROJ_L**_S**_A****.OUT - file containing the projectors and band window indices.
+#. PROJ.OUT -  specficies some information about the projectors.
+   (like atom equivalency, lm indices and so on) needed for reading into the TRIQS library.
+#. EIGVAL.OUT - contains the energies and latice vector coordinates for each k-point.
+#. EFERMI.OUT - contains the Fermi energy.
+#. KPOINTS.OUT - contains the k-point weights and lattice vectors.
+#. SYMCRYS.OUT - has the crystal symmetries used for symmetries observables.
+#. LATTICE.OUT - has lattice-Cartesian basis transformation matrices.
+#. GEOMETRY.OUT - file with the lattice positions of every atom of each species.
+
+Moreover, the Wannier charge density matrix (in WANCHARGE.OUT) and the Wannier spectral function (in WANSF_L**_S**_A****_0*.OUT) are calculated. These files are not used in the interface. 
+
+As a side note, there are two other tasks which also generate the Wannier projectors. Task 804 generates the same outputs as 805 except it doesn't calculate the Wannier charge and spectral function. Task 806 outputs the same information as 805, but it generates the projectors (and other k-dependent variables) on a different user defined ngridk mesh. These tasks are parallelized with both OpenMP and MPI.
+
+The Elk outputs are read into the TRIQS library using the following lines::
+
+  from triqs_dft_tools.converters.elk import *
+  Converter = ElkConverter(filename=filename, repacking=True)
+  Converter.convert_dft_input()
+
+The first two lines import and load the Elk converter module and the last line executes the conversion into the filename.h5 HDF5 file.
+
+
+Data for post-processing - Correlated Spectral functions
+--------------------------------------------------------
+
+In case you want to do post-processing of your data using the module :class:`SumkDFTTools <dft.sumk_dft_tools.SumkDFTTools>`, some more files have to be converted to the HDF5 archive. Some of this has been laid out in :ref:`analysis`, but the Elk specific functions are described in the following sections. Below, we will discuss how to input the information for correlated spectral functions (band structures) and which is then calculated using "spaghettis" in :ref:`analysis`. However, band character band structure plots have not yet been implemented.
+
+In Elk, the elk.in requires the altered flag::
+
+  task
+   820
+
+As well as the wanproj flag (which has be discussed previously) and the plot1d flag (refer to the Elk manual). The new output files of this task required for the interface are:
+
+#. BAND.OUT - the energy eigenvalues along the user specified path.
+#. PROJ_WANBAND.OUT - same as PROJ.OUT but for band structure projectors
+#. WANPROJ_L**_S**_A****_WANBAND.OUT - same as WANPROJ_L**_S**_A****.OUT
+    but for band structure projectors.
+
+(The ascii output files which have the new extension of _WANBAND.OUT are specific for this post processing calculation.)
+
+The band structure information is converted into TRIQS by using::
+
+  Converter.convert_bands_input()
+
+Spectral function from Elk inputs
+---------------------------------
+
+Elk does not calculate the theta projectors for partial DOS calculations. Instead, Elk outputs the band characters into the file BC.OUT when using the elk.in task::
+
+  task 
+  803 
+
+The contents of BC.OUT need to be converted into the HDF5 file by using the Elk Converter module::
+
+  from triqs_dft_tools.converters.elk import *
+  Converter = ElkConverter(filename=filename, repacking=True)
+  Converter.dft_band_characters()
+
+Once these have been saved to the HDF5 file (called "filename" here), the spectral function can be calculated with::
+
+  SK.elk_dos(broadening=0.0, with_Sigma=True, with_dc=True, pdos=False, nk=None)
+
+This outputs the total spectral function and the partial spectral function if enabled. Most of the user inputs are similar to the "SK.dos_parproj_basis()" module in :ref:`analysis`. The "pdos" flag when "True" enables the partial dos of each lm value to be calculated. It should be noted that these band characters are in Elk's irreducible lm basis and as such, the user has to check the irreducible representation used in Elk. This information can be found in the file ELMIREP.OUT after running task 10 (the DOS calculating task). The "nk" flag enables the calculation of the occupied spectral funciton. Here, nk needs to be the occupation density matrix (calculated from integrating the Green's function on the Matsubara axis) in the Bloch basis. This input needs to be in the same format as the occupation density matrix "deltaN" calculated in the sumk_DFT.calc_density_correction(dm_type='elk') module.
+
+
+Spectral function Contour Plots (Fermi Surfaces) from Elk inputs
+-----------------------------------------------------------------
+
+Here, we will discuss how to plot the Fermi surface contour or any other non-zero omega spectral function contour plot. This is currently tailored for the Elk inputs. From this point, we will refer to these contours as Fermi surfaces. The energy eigenvalues, projectors and so on required for the Fermi surface plot needs to be outputed from Elk. This is done by using::
+
+  task 
+  807 
+  
+in Elk, but unlike the previous Elk interface tasks, the k-mesh grid needs to be specified. This is done like using the same inputs as the Fermi surface calculations in Elk. In Elk, The user needs to specify the "plot3d" input flag used to generate the k-mesh which the interface variables are evaluated on. A simple example is for SrVO3 where plot3d would look something like::
+  
+  plot3d
+  0.0 0.0 0.0 !1) origin
+  1.0 0.0 0.0 !2) vertex 1
+  0.0 1.0 0.0 !3) vertex 2
+  0.0 0.0 1.0 !4) vertex 3
+  32 32 32    !5) k-mesh grid size
+
+Lines 1) to 4) specifies the corners (in lattice coordinates) of the k-grid box and line 5) is the grid size in each direction (see the Elk manual). If the user desires to plot a 2D plane, then the user should define the plane using lines 2) and 3) [relative to line 1)] and define line 4) to be the cross-product of lines 2) and 3) [i.e. the vector in line 4) is normal to the 2D plane]. The outputs will be in terms of the k-dependent quantities in the irreducible Brillouin zone (IBZ). The files needed for the interface are:
+
+#. EIGVAL_FS.OUT - same as EIGVAL.OUT but the output is of the Fermi surface calculation.
+#. KPOINT_FS.OUT - same as KPOINT.OUT but the output is of the Fermi surface calculation.   
+#. PROJ_FS.OUT - same as PROJ.OUT but the output is of the Fermi surface calculation.   
+#. WANPROJ_L**_S**_A****_FS.OUT - same as WANPROJ_L**_S**_A****.OUT but the output is of the Fermi surface calculation.   
+#. EFERMI.OUT - contains the Fermi energy.
+#. SYMCRYS.OUT - has the crystal symmetries used for symmetries observables.
+#. LATTICE.OUT - has lattice-Cartesian basis transformation matrices.
+
+(The ascii output files which have the extension of _FS.OUT are specific for this post processing calculation.)
+
+These outputs are converted to the HDF5 file by::
+
+  from triqs_dft_tools.converters.elk import *
+  Converter = ElkConverter(filename=filename, repacking=True)
+  Converter.convert_fs_input()
+
+The spectral function for the Fermi surface plots are calculated with::
+
+  SK.fs_plot(broadening=0.0, mesh=None, FS=True, plane=True, sym=True, orthvec=None, with_Sigma=True, with_dc=True)
+
+The new flags specify the following: 
+
+#. "FS" - determines whether the output will be the Fermi surface and uses the closest omega value to 0.0 in the mesh.  
+#. "plane" - required to specify whether the Elk input parameters were generated on a k-mesh plane.
+#. "sym" - needed if the IBZ will be folded out by using symmetry operations.
+#. "orthvec" - (numpy array of length 3) needs to be specified if using "plane" as this input is the orthonormal vector to the 2D plane required for the folding out process.
+
+To give the user a range of output capabilities, This routine can be used in the following ways:
+
+#. If using "with_Sigma", the mesh will be the same as the self-energy. However, by setting FS=False, the user can input a mesh option if they desire the "Fermi surface" plots for each omega value (commensurate with the self-energy mesh) within the input range.
+
+#. If the user is generating the DFT Spectral function plot (i.e. with_Sigma and with_dc both set to False), a mesh needs to be specified if FS=False. This function will output the spectral functions for the input mesh. Otherwise if FS is True, this would return the spectral function at omega=0.0.
+
+The output files will have the form of "Akw_FS_X.dat" (X being either up, down or ud) if FS=True or "Akw_X_omega_Y.dat" (Y being the omega mesh index) otherwise. The latter file will have the omega values within the file (the fourth column). The first three columns of both output file types specifies the cartesian lattice vector (kx, ky, kz) and the last column is the spectral function values.
+
+
+DFT+DMFT wavefunction dependent quantities
+------------------------------------------
+
+The DFT+DMFT wavefunctions and occupations are generated in Elk by diagonalizing the full DFT+DMFT density matrix at each k-point during task 808. These are used to update the electron density which is then used to solve the Kohn-Sham equations once to complete a FCSC DFT+DMFT cycle. It is possible to calculate quantities which are solely dependent on the wavefunctions and occupations by using the aforementioned diagonalized set. After generating the DMATDMFT.OUT file, these diagonalized wavefunctions and occupations are calculated by amending elk.in with the new task::
+
+  task
+   809
+
+This will write the new second variational eigenvectors and occupations in the EVECSV.OUT and OCCSV.OUT binary files respectively. Then the wavefunction dependent quantities implemented within Elk can be calculated using these DFT+DMFT wavefunctions and occupations. Note that this only works for energy independent quantities. Also, the user has to ensure that the second variational eigenvectors will be used in determining the wavefunction dependent quantities. This is done by looking for the variable "tevecsv" in init0.f90 of Elk's source code and making sure that this is set to .true. for the task number the user wishes to use.
+
+
+

doc/guide/conv_generalhk.rst

@@ -87,7 +87,7 @@ matrix of the imaginary part, and then move on to the next :math:`\mathbf{k}`-po
 
 The converter itself is used as::
 
-  from triqs_dft_tools.converters.hk_converter import *
+  from triqs_dft_tools.converters.hk import *
   Converter = HkConverter(filename = hkinputfile)
   Converter.convert_dft_input()
 
@@ -95,6 +95,6 @@ where :file:`hkinputfile` is the name of the input file described
 above. This produces the hdf file that you need for a DMFT calculation.
 
 For more options of this converter, have a look at the
-:ref:`refconverters` section of the reference manual.
+:py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 

doc/guide/conv_vasp.rst

@@ -1,50 +1,67 @@
 .. _convVASP:
 
-
+===================
 Interface with VASP
 ===================
 
-.. warning::
-  The VASP interface is in the alpha-version and the VASP part of it is not
-  yet publicly released. The documentation may, thus, be subject to changes
-  before the final release.
+The VASP interface relies on new options introduced since version 5.4.x In
+particular, a new INCAR-option `LOCPROJ
+<https://cms.mpi.univie.ac.at/wiki/index.php/LOCPROJ>`_, the new `LORBIT` modes
+13 and 14 have been added, and the new `ICHARG` mode 5 for charge
+self-consistent DFT+DMFT calculations have been added.
 
-*Limitations of the alpha-version:*
+The VASP interface methodologically builds on the so called projection on
+localized orbitals (PLO) scheme, where the resulting KS states from DFT are
+projected on localized orbitals, which defines a basis for setting up a
+Hubbard-like model Hamiltonian. Resulting in lattice object stored in `SumkDFT`.
+The implementation is presented in `M. Schüler et al. 2018 J. Phys.: Condens.
+Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_.
 
-  * The interface works correctly only if the k-point symmetries
-    are turned off during the VASP run (ISYM=-1).
+The interface consists of two parts, :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>`, a collection of
+python classes and functions converting the raw VASP output to proper projector
+functions, and the python based :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>`, which
+creates a h5 archive from the :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` output readable by
+`SumkDFT`. Therefore, the conversion consist always of two steps.
 
-  * Generation of projectors for k-point lines (option `Lines` in KPOINTS)
-    needed for Bloch spectral function calculations is not possible at the moment.
+Here, we will present a guide how the interface `can` be used to create input for a DMFT calculation, using SrVO3 as an example. Full examples can be found in the :ref:`tutorial section of DFTTools<tutorials>`.
 
-  * The interface currently supports only collinear-magnetism calculation
-    (this implis no spin-orbit coupling) and
-    spin-polarized projectors have not been tested.
+Limitations of the interface
+============================
 
-A detailed description of the VASP converter tool PLOVasp can be found
-in the :ref:`PLOVasp User's Guide <plovasp>`. Here, a quick-start guide is presented.
+* The interface works correctly only if the k-point symmetries
+  are turned off during the VASP run (ISYM=-1).
+* Generation of projectors for k-point lines (option `Lines` in KPOINTS)
+  needed for Bloch spectral function calculations is not possible at the moment.
+* The interface currently supports only collinear-magnetism calculation
+  (this implies no spin-orbit coupling) and spin-polarized projectors have not
+  been tested.
+* The converter needs the correct Fermi energy from VASP, which is read from
+  the LOCPROJ file. However, VASP by default does not output this information.
+  Please see `Remarks on the VASP version`_.
 
-The VASP interface relies on new options introduced since version
-5.4.x. In particular, a new INCAR-option `LOCPROJ`
-and new `LORBIT` modes 13 and 14 have been added.
+VASP: generating raw projectors
+===============================
 
-Option `LOCPROJ` selects a set of localized projectors that will
-be written to file `LOCPROJ` after a successful VASP run.
-A projector set is specified by site indices,
-labels of the target local states, and projector type:
+The VASP **INCAR** option `LOCPROJ` selects a set of localized projectors that
+will be written to the file **LOCPROJ** after a successful VASP run. A projector set is specified by site indices, labels of the target local states, and projector type:
 
   | `LOCPROJ = <sites> : <shells> : <projector type>`
 
-where `<sites>` represents a list of site indices separated by spaces,
-with the indices corresponding to the site position in the POSCAR file;
-`<shells>` specifies local states (see below);
-`<projector type>` chooses a particular type of the local basis function.
-The recommended projector type is `Pr 2`. The formalism for this type
-of projectors is presented in
-`M. Schüler et al. 2018 J. Phys.: Condens. Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_.
+where `<sites>` represents a list of site indices separated by spaces, with the
+indices corresponding to the site position in the **POSCAR** file; `<shells>`
+specifies local states (see below); `<projector type>` chooses a particular type
+of the local basis function. The recommended projector type is `Pr 2`. This will
+perform a projection of the Kohn-Sham states onto the VASP PAW projector
+functions. The number specified behind `Pr` is selecting a specific PAW channel,
+see the `VASP wiki page <https://cms.mpi.univie.ac.at/wiki/index.php/LOCPROJ>`_
+for more information. The formalism for this type of projectors is presented in
+`M. Schüler et al. 2018 J. Phys.: Condens. Matter 30 475901
+<https://doi.org/10.1088/1361-648X/aae80a>`_. For further details on the
+`LOCPROJ` flag also have a look in the `VASP wiki
+<https://cms.mpi.univie.ac.at/wiki/index.php/LOCPROJ>`_.
 
 The allowed labels of the local states defined in terms of cubic
-harmonics are:
+harmonics are (mind the order):
 
  * Entire shells: `s`, `p`, `d`, `f`
 
@@ -55,16 +72,25 @@ harmonics are:
  * `f`-states: `fy(3x2-y2)`, `fxyz`, `fyz2`, `fz3`,
    `fxz2`, `fz(x2-y2)`, `fx(x2-3y2)`.
 
-For projector type `Pr 2`, one should also set `LORBIT = 14` in the INCAR file
-and provide parameters `EMIN`, `EMAX`, defining, in this case, an
-energy range (energy window) corresponding to the valence states.
-Note that, as in the case
-of a DOS calculation, the position of the valence states depends on the
-Fermi level, which can usually be found at the end of the OUTCAR file.
+For projector type `Pr`, one should ideally also set `LORBIT = 14` in the
+INCAR file and provide parameters `EMIN`, `EMAX`, defining, in this case, an
+energy range (energy window) corresponding to the valence states. Note that,
+as in the case of a DOS calculation, the position of the valence states
+depends on the Fermi level, which can usually be found at the end of the
+OUTCAR file. Setting `LORBIT=14` will perform an automatic optimization of
+the PAW projector channel as described in `M. Schüler et al. 2018 J. Phys.:
+Condens. Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_, by
+using a linear combination of the PAW channels, to maximize the overlap in
+the chosen energy window between the projector and the Kohn-Sham state.
+Therefore, setting `LORBIT=14` will let VASP ignore the channel specified
+after `Pr`. This optimization is only performed for the projector type `Pr`,
+not for `Ps` and obviously not for `Hy`. We recommend to specify the PAW
+channel anyway, in case one forgets to set `LORBIT=14`.
 
-For example, in case of SrVO3 one may first want to perform a self-consistent
-calculation, then set `ICHARGE = 1` and add the following additional
-lines into INCAR (provided that V is the second ion in POSCAR):
+In case of SrVO3 one may first want to perform a self-consistent
+calculation to know the Fermi level and the rough position of the target states.
+In the next step one sets `ICHARG = 1` and adds the following additional lines
+into INCAR (provided that V is the second ion in POSCAR):
 
   | `EMIN = 3.0`
   | `EMAX = 8.0`
@@ -72,73 +98,347 @@ lines into INCAR (provided that V is the second ion in POSCAR):
   | `LOCPROJ = 2 : d : Pr 2`
 
 The energy range does not have to be precise. Important is that it has a large
-overlap with valence bands and no overlap with semi-core or high unoccupied states.
+overlap with valence bands and no overlap with semi-core or high unoccupied
+states. This **INCAR** will calculate and write-out projections for all five d-orbitals.
+
+
+VASP input-output
+-----------------
+
+The calculated projections :math:`\langle \chi_L | \Psi_\mu \rangle` are written
+into files **PROJCAR** and **LOCPROJ**. The difference between these two files
+is that **LOCPROJ** contains raw matrices without any reference to
+sites/orbitals, while **PROJCAR** is more detailed. In particular, the
+information that can be obtained for each projector from **PROJCAR** is the
+following:
+
+  * site (and species) index
+  * for each `k`-point and band: a set of complex numbers for labeled orbitals
+
+At the same time, **LOCPROJ** contains the total number of projectors (as well
+as the number of `k`-points, bands, and spin channels) in the first line, which
+can be used to allocate the arrays before parsing.
 
 Conversion for the DMFT self-consistency cycle
-----------------------------------------------
+==============================================
 
-The projectors generated by VASP require certain post-processing before
-they can be used for DMFT calculations. The most important step is to normalize
+The projectors generated by VASP require certain post-processing before they can
+be used for DMFT calculations. The most important step is to (ortho-)normalize
 them within an energy window that selects band states relevant for the impurity
-problem. Note that this energy window is different from the one described above
-and it must be chosen independently of the energy
-range given by `EMIN, EMAX` in INCAR.
+problem. This will create proper Wannier functions of the initial projections
+produced by VASP. Note that this energy window is different from the one
+described above and it must be chosen independently of the energy range given by
+`EMIN, EMAX` in the **INCAR** VASP input file. This part is done in `PLOVASP`.
 
-Post-processing of `LOCPROJ` data is generally done as follows:
 
-#. Prepare an input file `<name>.cfg` (e.g., `plo.cfg`) that describes the definition
-   of your impurity problem (more details below).
+PLOVASP: converting VASP output
+--------------------------------
 
-#. Extract the value of the Fermi level from OUTCAR and paste it at the end of
-   the first line of LOCPROJ.
+:py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` is a collection of python functions and classes, post-processing the raw VASP `LOCPROJ` output creating proper projector functions.
 
-#. Run :program:`plovasp` with the input file as an argument, e.g.:
+The following VASP files are used by PLOVASP:
+  * PROJCAR, LOCPROJ: raw projectors generated by VASP-PLO interface
+  * EIGENVAL: Kohn-Sham eigenvalues as well as `k`-points with weights and Fermi weights
+  * IBZKPT: `k`-point data (:math:`\Gamma`)
+  * POSCAR: crystal structure data
 
-     | `plovasp plo.cfg`
+To run `PLOVASP`, one first prepares an input file `<name>.cfg` (default name `plo.cfg`) that describes the definition of the correlated subspace. For SrVO3 this input file would look like this:
 
-   This requires that the TRIQS paths are set correctly (see Installation
-   of TRIQS).
+.. literalinclude:: ../tutorials/svo_vasp/plo.cfg
 
-If everything goes right one gets files `<name>.ctrl` and `<name>.pg1`.
-These files are needed for the converter that will be invoked in your
-DMFT script.
+In the [section] general, the `DOSMESH` defines an energy window and number of
+data points, which lets the converter calculate the density of states of the
+created projector functions in a given energy window. Each projector shell is
+defined by a section `[Shell 1]` where the number can be arbitrary and used only
+for user convenience. Several parameters are required
 
-The format of input file `<name>.cfg` is described in details in
-the :ref:`User's Guide <plovasp>`. Here we just consider a simple example for the case
-of SrVO3:
-
-.. literalinclude:: images_scripts/srvo3.cfg
-
-A projector shell is defined by a section `[Shell 1]` where the number
-can be arbitrary and used only for user convenience. Several
-parameters are required
-
-- **IONS**: list of site indices which must be a subset of indices
-  given earlier in `LOCPROJ`.
+- **IONS**: list of site indices which must be a subset of indices given earlier
+  in the VASP INCAR `LOCPROJ` flag. Note: If projections are performed for
+  multiple sites one can specify symmetry equivalent sites with brackets: `[2
+  3]`. Here the projector are generated for ions 2 and 3, but they will be
+  marked as symmetry equivalent later in 'SumkDFT'.
 - **LSHELL**: :math:`l`-quantum number of the projector shell; the corresponding
   orbitals must be present in `LOCPROJ`.
 - **EWINDOW**: energy window in which the projectors are normalized;
   note that the energies are defined with respect to the Fermi level.
 
-Option **TRANSFORM** is optional but here, it is specified to extract
-only three :math:`t_{2g}` orbitals out of five `d` orbitals given by
-:math:`l = 2`.
+The Option **TRANSFORM** is optional here, and it is specified to extract
+only the three :math:`t_{2g}` orbitals out of the five `d` orbitals given by
+:math:`l = 2`. A detailed explanation of all input parameters can be found
+further below `PLOVASP detailed guide`_.
 
-The conversion to a h5-file is performed in the same way as for Wien2TRIQS::
+Next, the converter is executed. This can be done by calling :program:`PLOVASP` directly in the command line with the input file as an argument, e.g.:
+     | `plovasp plo.cfg`
 
-    from triqs_dft_tools.converters.vasp_converter import *
-    Converter = VaspConverter(filename = filename)
+or embedded in a python script as::
+
+    import triqs_dft_tools.converters.plovasp.converter as plo_converter
+    # Generate and store PLOs
+    plo_converter.generate_and_output_as_text('plo.cfg', vasp_dir='./')
+
+This will create the xml files `vasp.ctrl` and `vasp.pg1` containing the orthonormalized projector functions readable by the :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>`. Moreover, :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` will output important information of the orthonormalization process, such as the density matrix of the correlated shell and the local Hamiltonian.
+
+Running the VASP converter
+-------------------------------------
+
+The actual conversion to a h5-file is performed with the orthonormalized projector functions readable by the :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>` in the same fashion as with the other `DFTTools` converters::
+
+    from triqs_dft_tools.converters.vasp import *
+    Converter = VaspConverter(filename = 'vasp')
     Converter.convert_dft_input()
 
-As usual, the resulting h5-file can then be used with the SumkDFT class.
+As usual, the resulting h5-file can then be used with the SumkDFT class::
+    sk = SumkDFTTools(hdf_file='vasp.h5')
 
-Note that the automatic detection of the correct block structure might
-fail for VASP inputs.
-This can be circumvented by setting a bigger value of the threshold in
-:class:`SumkDFT <dft.sumk_dft.SumkDFT>`, e.g.::
+Note that the automatic detection of the correct block structure might fail for
+VASP inputs. This can be circumvented by setting a bigger value of the threshold
+in :class:`SumkDFT <dft.sumk_dft.SumkDFT>`, e.g.::
 
     SK.analyse_block_structure(threshold = 1e-4)
 
-However, do this only after a careful study of the density matrix and
-the projected DOS in the localized basis.
+However, this should only be done after a careful study of the density matrix and the projected DOS in the localized basis. For the complete process for SrVO3 see the tutorial for the VASP interface `here <../tutorials/svo_vasp/svo_notebook.html>`_.
 
+PLOVASP detailed guide
+======================
+
+The general purpose of the PLOVASP tool is to transform raw, non-normalized
+projectors generated by VASP into normalized projectors corresponding to
+user-defined projected localized orbitals (PLO). To enhance the performance
+parsing the raw VASP output files, the parser is implemented in plain C. The
+idea is that the python part of the parser first reads the first line of
+**LOCPROJ** and then calls the C-routine with necessary parameters to parse
+**PROJCAR**. The resulting PLOs can then be used for DFT+DMFT calculations with
+or without charge self-consistency. PLOVASP also provides some utilities for
+basic analysis of the generated projectors, such as outputting density matrices,
+local Hamiltonians, and projected density of states.
+
+PLOs are determined by the energy window in which the raw projectors are
+normalized. This allows to define either atomic-like strongly localized Wannier
+functions (large energy window) or extended Wannier functions focusing on
+selected low-energy states (small energy window).
+
+In PLOVASP, all projectors sharing the same energy window are combined into a
+`projector group`. This allows one in principal to define several groups with
+different energy windows for the same set of raw projectors. Note: multiple groups are not yet implemented.
+
+A set of projectors defined on sites related to each other either by symmetry
+or by an atomic sort, along with a set of :math:`l`, :math:`m` quantum numbers,
+forms a `projector shell`. There could be several projectors shells in a
+projector group, implying that they will be normalized within the same energy
+window.
+
+Projector shells and groups are specified by a user-defined input file whose
+format is described below. Additionally, each shell can be marked correlated or non-correlated, to tell `SumkDFT` whether or not these should be treated in the DMFT impurity problem.
+
+Input file format
+-----------------
+
+The input file is written in the standard config-file format.
+Parameters (or 'options') are grouped into sections specified as
+`[Section name]`. All parameters must be defined inside some section.
+
+A PLOVASP input file can contain three types of sections:
+
+#. **[General]**: includes parameters that are independent
+   of a particular projector set, such as the Fermi level, additional
+   output (e.g. the density of states), etc.
+#. **[Group <Ng>]**: describes projector groups, i.e. a set of
+   projectors sharing the same energy window and normalization type.
+   At the moment, DFTtools support only one projector group, therefore
+   there should be no more than one projector group.
+#. **[Shell <Ns>]**: contains parameters of a projector shell labelled
+   with `<Ns>`. If there is only one group section and one shell section,
+   the group section can be omitted but in this case, the group required
+   parameters must be provided inside the shell section.
+
+Section [General]
+"""""""""""""""""
+
+The entire section is optional and it contains four parameters:
+
+*  **BASENAME** (string): provides a base name for output files.
+   Default filenames are :file:`vasp.*`.
+*  **DOSMESH** ([float float] integer): if this parameter is given,
+   the projected density of states for each projected orbital will be
+   evaluated and stored to files :file:`pdos_<s>_<n>.dat`, where `s` is the
+   shell index and `n` the ion index. The energy mesh is defined by three
+   numbers: `EMIN`  `EMAX`  `NPOINTS`. The first two
+   can be omitted in which case they are taken to be equal to the projector
+   energy window. **Important note**: at the moment this option works
+   only if the tetrahedron integration method (`ISMEAR = -4` or `-5`)
+   is used in VASP to produce `LOCPROJ`.
+*  **EFERMI** (float): provides the Fermi level. This value overrides
+   the one extracted from VASP output files.
+*  **HK** (True/False): If True, the projectors are applied the the Kohn-Sham
+   eigenvalues which results in a Hamitlonian H(k) in orbital basis. The H(k)
+   is written for each group to a file :file:`Basename.hk<Ng>`. It is recommended
+   to also set `COMPLEMENT = True` (see below). Default is False.
+
+There are no required parameters in this section.
+
+Section [Shell]
+"""""""""""""""
+
+This section specifies a projector shell. Each `[Shell]` section must be
+labeled by an index, e.g. `[Shell 1]`. These indices can then be referenced
+in a `[Group]` section.
+
+In each `[Shell]` section two parameters are required:
+
+*  **IONS** (list of integer): indices of sites included in the shell.
+   The sites can be given either by a list of integers `IONS = 5 6 7 8`
+   or by a range `IONS = 5..8`. The site indices must be compatible with
+   the POSCAR file. Morever, sites can be marked to be identical by 
+   grouping them with brackets, i.e. `IONS = [5 6] [7 8]` will mark the
+   sites 5 and 6 in the POSCAR (and of course also 7 and 8) to be idential.
+   This will mark these correlated site as equivalent, and only one 
+   impurity problem per bracket group is generated.
+*  **LSHELL** (integer): :math:`l` quantum number of the desired local states.
+
+It is important that a given combination of site indices and local states
+given by `LSHELL` must be present in the LOCPROJ file.
+
+There are additional optional parameters that allow one to transform
+the local states:
+
+*  **CORR** (True/False): Determines if shell is correlated or not. At least one
+   shell has to be correlated. Default is True.
+*  **SORT** (integer): Overrides the default detection of ion sorts by supplying
+   an integer. Default is `None`, for which the default behavior is retained.
+*  **TRANSFORM** (matrix): local transformation matrix applied to all states
+   in the projector shell. The matrix is defined by a (multiline) block
+   of floats, with each line corresponding to a row. The number of columns
+   must be equal to :math:`2 l + 1`, with :math:`l` given by `LSHELL`. Only real matrices
+   are allowed. This parameter can be useful to select certain subset of
+   orbitals or perform a simple global rotation.
+*  **TRANSFILE** (string): name of the file containing transformation
+   matrices for each site. This option allows for a full-fledged functionality
+   when it comes to local state transformations. The format of this file
+   is described :ref:`below <transformation_file>`.
+
+Section [Group]
+"""""""""""""""
+
+Each defined projector shell must be part of a projector group. In the current
+implementation of DFTtools only a single group (labelled by any integer, e.g. `[Group 1]`)
+is supported. This implies that all projector shells
+must be included in this group.
+
+Required parameters for any group are the following:
+
+*  **SHELLS** (list of integers): indices of projector shells included in the group.
+   All defined shells must be grouped.
+*  **EWINDOW** (float float): the energy window specified by two floats: bottom
+   and top. All projectors in the current group are going to be normalized within
+   this window. *Note*: This option must be specified inside the `[Shell]` section
+   if only one shell is defined and the `[Group]` section is omitted.
+
+Optional group parameters:
+
+*  **NORMALIZE** (True/False): specifies whether projectors in the group are
+   to be normalized. The default value is **True**.
+*  **NORMION** (True/False): specifies whether projectors are normalized on
+   a per-site (per-ion) basis. That is, if `NORMION = True`, the orthogonality
+   condition will be enforced on each site separately but the Wannier functions
+   on different sites will not be orthogonal. If `NORMION = False`, the Wannier functions
+   on different sites included in the group will be orthogonal to each other. The default value is **True**
+*  **BANDS** (int int): the energy window specified by two ints: band index of
+   lowest band and band index of highest band. Using this overrides the selection
+   in `EWINDOW`.
+*  **COMPLEMENT** (True/False). If True, the orthogonal complement is calculated
+   resulting in unitary (quadratic) projectors, i.e., the same number of orbitals
+   as bands. It is required to have an equal number of bands in the energy window
+   at each k-point. Default is False.
+
+
+.. _transformation_file:
+
+File of transformation matrices
+"""""""""""""""""""""""""""""""
+
+.. warning::
+  The description below applies only to collinear cases (i.e., without spin-orbit
+  coupling). In this case, the matrices are spin-independent.
+
+The file specified by option `TRANSFILE` contains transformation matrices
+for each ion.  Each line must contain a series of floats whose number is either equal to
+the number of orbitals :math:`N_{orb}` (in this case the transformation matrices
+are assumed to be real) or to :math:`2 N_{orb}` (for the complex transformation matrices).
+The total number of lines :math:`N` must be a multiple of the number of ions :math:`N_{ion}`
+and the ratio :math:`N / N_{ion}`, then, gives the dimension of the transformed
+orbital space. The lines with floats can be separated by any number of empty or
+comment lines (starting from `#`), which are ignored.
+
+A very simple example is a transformation matrix that selects the :math:`t_{2g}` manifold.
+For two correlated sites, one can define the file as follows:
+::
+
+  # Site 1
+    1.0   0.0   0.0   0.0   0.0
+    0.0   1.0   0.0   0.0   0.0
+    0.0   0.0   0.0   1.0   0.0
+
+  # Site 2
+    1.0   0.0   0.0   0.0   0.0
+    0.0   1.0   0.0   0.0   0.0
+    0.0   0.0   0.0   1.0   0.0
+
+Remarks on the VASP version
+===============================
+
+In the current version of the interface the Fermi energy is extracted from the
+DOSCAR. However, if one pursues to do charge self-consistent calculations one 
+needs to write the Fermi energy to the projectors (`LOCPROJ` file), as the DOSCAR 
+is only updated after a full SCF/NSCF run. The file should contain the Fermi energy 
+in the header. One can either copy the Fermi energy manually there after a successful
+VASP run, or modify the VASP source code slightly, by replacing the following line in
+`locproj.F` (around line 695):
+::
+
+  <   WRITE(99,'(4I6,"  # of spin, # of k-points, # of bands, # of proj" )') NS,NK,NB,NF
+  ---
+  >   WRITE(99,'(4I6,F12.7,"  # of spin, # of k-points, # of bands, # of proj, Efermi" )') W%WDES%NCDIJ,NK,NB,NF,EFERMI
+
+Now one needs to pass additionally the variable `EFERMI` to the function, by changing (at arount line 560): 
+::
+
+  <   SUBROUTINE LPRJ_WRITE(IU6,IU0,W)
+  ---
+  >   SUBROUTINE LPRJ_WRITE(IU6,IU0,W,EFERMI)
+      REAL(q) :: EFERMI
+
+Next, we need to pass this option when calling from `electron.F` and `main.F` 
+(just search for LPRJ_WRITE in the files) and change all occurences as follows: 
+::
+
+  <   CALL LPRJ_WRITE(IO%IU6, IO%IU0, W)
+  ---
+  >   CALL LPRJ_WRITE(IO%IU6, IO%IU0, W, EFERMI)
+
+Now Vasp should print in the header of the `LOCPROJ` file additionally the Fermi energy.
+
+
+Another critical point for CSC calculations is the function call of
+`LPRJ_LDApU` in VASP. This function is not needed, and was left there for debug
+purposes, but is called every iteration. Removing the call to this function in `electron.F` in line 644 speeds up the calculation significantly in the `ICHARG=5` mode. Moreover, this prevents VASP from generating the `GAMMA` file, which should ideally only be done by the DMFT code after a successful DMFT step, and then be read by VASP.
+
+
+Furthermore, there is a bug in `fileio.F` around line 1710 where VASP tries to
+print "reading the density matrix from Gamma". This should be done only by the
+master node, and VASP gets stuck sometimes. Adding a
+::
+
+  IF (IO%IU0>=0) THEN
+  ...
+  ENDIF
+
+statement resolves this issue. A similar problem occurs, when VASP writes the
+`OSZICAR` file and a buffer is stuck. Adding a `flush` to the buffer in
+`electron.F` around line 580 after
+::
+
+  CALL STOP_TIMING("G",IO%IU6,"DOS")
+  flush(17)
+  print *, ' '
+
+resolves this issue. Otherwise the OSZICAR file is not written properly.

doc/guide/conv_wien2k.rst

@@ -68,10 +68,33 @@ is given by the following 3 to 5 lines:
 
 These lines have to be repeated for each inequivalent atom.
 
-The last line gives the energy window, relative to the Fermi energy,
-that is used for the projective Wannier functions. Note that, in
-accordance with Wien2k, we give energies in Rydberg units!
+The last line gives the lower and upper limit of the energy window,
+relative to the Fermi energy, which is used for the projective Wannier functions.
+Note that, in accordance with Wien2k, we give energies in Rydberg units!
 
+The third number is an optional flag to switch between different modes:
+
+#. 0: The projectors are constructed for the given energy window. The number
+   of bands within the window is usually different at each k-point which
+   will be reflected by the projectors, too. This is the default mode
+   which is also used if no mode flag is provided.
+#. 1: The lowest and highest band indices within the given energy window
+   are calculated. The resulting indices are used at all k-points.
+   Bands which fall within the window only in some parts of the Brillouin zone
+   are fully taken into account. Keep in mind that a different set of k-points
+   or the -band option can change the lower or upper index. This can be avoided
+   by using mode 2.
+#. 2: In this mode the first two values of the line are interpreted as lower
+   and upper band indices to be included in the projective subspace. For example,
+   if the line reads `21 23 2`, bands number 21, 22 and 23 are included at all
+   k-points. For SrVO3 this corresponds to the t2g bands around the Fermi energy.
+   The lowest possible index is 1. Note that the indices need to be provided as integer.
+
+In all modes the used energy range, i.e. band range, is printed to the
+:program:`dmftproj` output.
+
+We also provide a simple python script `init_dmftpr` that creates the input file 
+interactively with user input in the shell, when executed in the wien2k run dir. 
 After setting up the :file:`case.indmftpr` input file, you run:
 
   `dmftproj`
@@ -94,9 +117,9 @@ directory name):
 
 Now we convert these files into an hdf5 file that can be used for the
 DMFT calculations. For this purpose we
-use the python module :class:`Wien2kConverter <dft.converters.wien2k_converter.Wien2kConverter>`. It is initialized as::
+use the python module :class:`Wien2kConverter <dft.converters.wien2k.Wien2kConverter>`. It is initialized as::
 
-  from triqs_dft_tools.converters.wien2k_converter import *
+  from triqs_dft_tools.converters.wien2k import *
   Converter = Wien2kConverter(filename = case)
 
 The only necessary parameter to this construction is the parameter `filename`.
@@ -105,7 +128,7 @@ example, the :program:`Wien2k` naming convention is that all files have the
 same name, but different extensions, :file:`case.*`. The constructor opens
 an hdf5 archive, named :file:`case.h5`, where all relevant data will be
 stored. For other parameters of the constructor please visit the
-:ref:`refconverters` section of the reference manual.
+:py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 After initializing the interface module, we can now convert the input
 text files to the hdf5 archive by::
@@ -158,7 +181,7 @@ and convert the input for :class:`SumkDFTTools <dft.sumk_dft_tools.SumkDFTTools>
 
 After having converted this input, you can further proceed with the
 :ref:`analysis`. For more options on the converter module, please have
-a look at the :ref:`refconverters` section of the reference manual.
+a look at the :py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 Data for transport calculations
 -------------------------------

doc/guide/conversion.rst

@@ -1,22 +1,23 @@
 .. _conversion:
 
-Supported interfaces 
+Supported interfaces
 ====================
 
 The first step for a DMFT calculation is to provide the necessary
 input based on a DFT calculation. We will not review how to do the DFT
 calculation here in this documentation, but refer the user to the
 documentation and tutorials that come with the actual DFT
-package. At the moment, there are two full charge self consistent interfaces, for the
-Wien2k and the VASP DFT packages, resp. In addition, there is an interface to Wannier90, as well
-as a light-weight general-purpose interface. In the following, we will describe the usage of these 
+package. At the moment, there are three full charge self consistent interfaces, for the
+Wien2k, VASP and Elk DFT packages, resp. In addition, there is an interface to Wannier90, as well
+as a light-weight general-purpose interface. In the following, we will describe the usage of these
 conversion tools.
 
 .. toctree::
-   :maxdepth: 2
-   
+   :maxdepth: 3
+
    conv_wien2k
    conv_vasp
+   conv_elk
    conv_W90
    conv_generalhk
 

doc/guide/dftdmft_selfcons.rst

@@ -37,7 +37,7 @@ that for one-shot calculations. Only at the very end we have to calculate the mo
 and store it in a format such that Wien2k can read it. Therefore, after the DMFT loop that we saw in the
 previous section, we symmetrise the self energy, and recalculate the impurity Green function::
 
-  SK.symm_deg_gf(S.Sigma,orb=0)
+  SK.symm_deg_gf(S.Sigma,ish=0)
   S.G_iw << inverse(S.G0_iw) - S.Sigma_iw
   S.G_iw.invert()
 
@@ -124,28 +124,96 @@ example how such a self-consistent calculation is performed from scratch.
 VASP + PLOVasp
 --------------
 
-.. warning::
-  This is a preliminary documentation valid for the alpha-version of the interface.
-  Modifications to the implementation might be introduced before the final release.
+Unlike Wien2k implementation the charge self-consistent DMFT cycle in the
+framework of PLOVasp interface is controlled by an external script. Because of
+the specific way the DFT self-consistency is implemented in VASP the latter has
+to run parallel to the DMFT script, with the synchronisation being ensured by a
+lock file.
 
-Unlike Wien2k implementation the charge self-consistent DMFT cycle
-in the framework of PLOVasp interface is controlled by an external script.
-Because of the specific way the DFT self-consistency is implemented in VASP
-the latter has to run parallel to the DMFT script, with the synchronisation being
-ensured by a lock file. PLOVasp interface provides a shell-script :program:`vasp_dmft.sh`
-which takes care of the process management. The user must, however, specify a path
-to VASP code and provide the DMFT Python-script.
+Once VASP reaches the point where the projectors are generated
+it creates a lock file `vasp.lock` and waits until the lock file is
+removed. The shell script, in turn, waits for the VASP process and once
+the lock file is created it starts a DMFT iteration. The DMFT iteration
+must finish by generating a Kohn-Sham (KS) density matrix (file `GAMMA`)
+and removing the lock file. The VASP process then reads in `GAMMA`
+and proceeds with the next iteration. PLOVasp interface provides a shell-script :program:`vasp_dmft` (in the triqs bin directory):
+::
+  vasp_dmft [-n <number of cores>] -i <number of iterations>  -j <number of VASP iterations with fixed charge density> [-v <VASP version>] [-p <path to VASP directory>] [<dmft_script.py>]
+
+       If the number of cores is not specified it is set to 1 by default.
+       Set the number of times the dmft solver is called with -i <number of iterations>
+
+       Set the number of VASP iteration with a fixed charge density update
+       inbetween the dmft runs with -j <number of VASP iterations with fixed charge density>
+
+       Set the version of VASP by -v standard(default)/no_gamma_write to
+       specify if VASP writes the GAMMA file or not.
+
+       If the path to VASP directory is not specified it must be provided by a
+       variable VASP_DIR.
+
+       <dmft_script.py> must provide an importable function 'dmft_cycle()'
+       which is invoked once per DFT+DMFT iteration. If the script name is
+       omitted the default name 'csc_dmft.py' is used.
+
+which takes care of the process management. The user must, however, specify a path to VASP code and provide the DMFT Python-script. See for an example :ref:`NiO CSC tutorial<nio_csc>`.
 
 The user-provided script is almost the same as for Wien2k charge self-consistent
-calculations with the main difference that its functionality (apart from
-the lines importing other modules) should be placed inside a function `dmft_cycle()`
-which will be called every DMFT cycle. Another difference is the way
-function `calc_density_correction()` works.
+calculations with the main difference that its functionality (apart from the
+lines importing other modules) should be placed inside a function `dmft_cycle()`
+which will be called every DMFT cycle.
+
+VASP has a special INCAR `ICHARG=5` mode, that has to be switched on to make VASP wait for the `vasp.lock` file, and read the updated charge density after each step. One should add the following lines to the `INCAR` file::
+
+  ICHARG = 5
+  NELM = 1000
+  NELMIN = 1000
+
+Technically, VASP runs with `ICHARG=5` in a SCF mode, and adding the DMFT
+changes to the DFT density in each step, so that the full DFT+DMFT charge
+density is constructed in every step. This is only done in VASP because only the
+changes to the DFT density are read by VASP not the full DFT+DMFT density.
+Moreover, one should always start with a converged `WAVECAR` file, or make sure,
+that the KS states are well converged before the first projectors are created!
+To understand the difference please make sure to read `ISTART flag VASP wiki
+<https://www.vasp.at/wiki/index.php/ISTART>`_. Furthermore, the flags `NELM` and
+`NELMIN` ensure that VASP does not terminate after the default number of
+iterations of 60.
+
+
+Elk
+---------
+
+The Elk CSC implementation is fairly similar to the Wien2k implementation. At the end of the :ref:`DMFT python script <SrVO3_elk>`, the density matrix in Bloch space needs to be calculated along with the correlation energy. This is written to DMATDMFT.OUT. An example of this (using the Migdal correlation energy formula) is given below::
+
+  #output the density matrix for Elk interface
+  dN, d = SK.calc_density_correction(dm_type='elk')
+  #correlation energy via the Migdal formula
+  correnerg = 0.5 * (S.G_iw * S.Sigma_iw).total_density()
+  #subtract the double counting energy
+  correnerg -= SK.dc_energ[0]
+  #convert to Hartree
+  correnerg = correnerg/SK.energy_unit
+  #save the correction to energy
+  if (mpi.is_master_node()):
+    f=open('DMATDMFT.OUT','a')
+    f.write("%.16f\n"%correnerg)
+    f.close()
+
+To read this into Elk and update the electron density, run task 808. So elk.in is amended with the following::
+
+  task
+   808
+
+This solves the Kohn-Sham equations once with the updated electron density and outputs the new set of energy eigenvalues and wavefunctions. To start the next fully charge self-consistent DFT+DMFT cycle (FCSC), a new set of projectors need to be generated (using task 805) and the whole procedure continues until convergence. The Elk potential rms value for each FCSC DFT+DMFT cycle is given in DMFT_INFO.OUT. An extensive example for SrVO:math:`_3` can be found here: :ref:`Elk SVO tutorial <SrVO3_elk>`.
+
+This FCSC method should be universal irrespective to what type of ground state calculation performed. However, not all types of ground state calculations have been tested.
+
 
 Other DFT codes
 ---------------
 
-The extension to other DFT codes is straight forward. As described
+The extension to other DFT codes is straightforward. As described
 here, one needs to implement the correlated density matrix to be used
 for the calculation of the charge density. This implementation will of
 course depend on the DFT package, and might be easy to do or a quite

doc/guide/dftdmft_singleshot.rst

@@ -80,8 +80,8 @@ for :emphasis:`use_dc_formula` are:
 
 At the end of the calculation, we can save the Green function and self energy into a file::
 
-    from pytriqs.archive import HDFArchive
-    import pytriqs.utility.mpi as mpi
+    from h5 import HDFArchive
+    import triqs.utility.mpi as mpi
     if mpi.is_master_node():
         ar = HDFArchive("YourDFTDMFTcalculation.h5",'w')
         ar["G"] = S.G_iw

doc/guide/images_scripts/LaVO3_w90.inp

@@ -5,3 +5,4 @@
  1  0  2  3  0  0       # atom, sort, l, dim, SO, irep
  2  0  2  3  0  0       # atom, sort, l, dim, SO, irep
  3  0  2  3  0  0       # atom, sort, l, dim, SO, irep
+0.0                     # DFT Fermi Energy (optional)

doc/guide/plovasp.rst

@@ -1,167 +0,0 @@
-.. _plovasp:
-
-PLOVasp
-=======
-
-The general purpose of the PLOVasp tool is to transform raw, non-normalized
-projectors generated by VASP into normalized projectors corresponding to
-user-defined projected localized orbitals (PLO).  The PLOs can then be used for
-DFT+DMFT calculations with or without charge self-consistency. PLOVasp also
-provides some utilities for basic analysis of the generated projectors, such as
-outputting density matrices, local Hamiltonians, and projected density of
-states.
-
-PLOs are determined by the energy window in which the raw projectors are
-normalized. This allows to define either atomic-like strongly localized Wannier
-functions (large energy window) or extended Wannier functions focusing on
-selected low-energy states (small energy window).
-
-In PLOVasp, all projectors sharing the same energy window are combined into a
-`projector group`. Technically, this allows one to define several groups with
-different energy windows for the same set of raw projectors. Note, however,
-that DFTtools does not support projector groups at the moment but this feature
-might appear in future releases.
-
-A set of projectors defined on sites related to each other either by symmetry
-or by an atomic sort, along with a set of :math:`l`, :math:`m` quantum numbers,
-forms a `projector shell`. There could be several projectors shells in a
-projector group, implying that they will be normalized within the same energy
-window.
-
-Projector shells and groups are specified by a user-defined input file whose
-format is described below.
-
-Input file format
------------------
-
-The input file is written in the standard config-file format.
-Parameters (or 'options') are grouped into sections specified as
-`[Section name]`. All parameters must be defined inside some section.
-
-A PLOVasp input file can contain three types of sections:
-
-#. **[General]**: includes parameters that are independent
-   of a particular projector set, such as the Fermi level, additional
-   output (e.g. the density of states), etc.
-#. **[Group <Ng>]**: describes projector groups, i.e. a set of
-   projectors sharing the same energy window and normalization type.
-   At the moment, DFTtools support only one projector group, therefore
-   there should be no more than one projector group.
-#. **[Shell <Ns>]**: contains parameters of a projector shell labelled
-   with `<Ns>`. If there is only one group section and one shell section,
-   the group section can be omitted but in this case, the group required
-   parameters must be provided inside the shell section.
-
-Section [General]
-"""""""""""""""""
-
-The entire section is optional and it contains three parameters:
-
-*  **BASENAME** (string): provides a base name for output files.
-   Default filenames are :file:`vasp.*`.
-*  **DOSMESH** ([float float] integer): if this parameter is given,
-   the projected density of states for each projected orbital will be
-   evaluated and stored to files :file:`pdos_<n>.dat`, where `n` is the
-   orbital index. The energy
-   mesh is defined by three numbers: `EMIN`  `EMAX`  `NPOINTS`. The first two
-   can be omitted in which case they are taken to be equal to the projector
-   energy window. **Important note**: at the moment this option works
-   only if the tetrahedron integration method (`ISMEAR = -4` or `-5`)
-   is used in VASP to produce `LOCPROJ`.
-*  **EFERMI** (float): provides the Fermi level. This value overrides
-   the one extracted from VASP output files.
-
-There are no required parameters in this section.
-
-Section [Shell]
-"""""""""""""""
-
-This section specifies a projector shell. Each `[Shell]` section must be
-labeled by an index, e.g. `[Shell 1]`. These indices can then be referenced
-in a `[Group]` section.
-
-In each `[Shell]` section two parameters are required:
-
-*  **IONS** (list of integer): indices of sites included in the shell.
-   The sites can be given either by a list of integers `IONS = 5 6 7 8`
-   or by a range `IONS = 5..8`. The site indices must be compatible with
-   the POSCAR file.
-*  **LSHELL** (integer): :math:`l` quantum number of the desired local states.
-
-It is important that a given combination of site indices and local states
-given by `LSHELL` must be present in the LOCPROJ file.
-
-There are additional optional parameters that allow one to transform
-the local states:
-
-*  **TRANSFORM** (matrix): local transformation matrix applied to all states
-   in the projector shell. The matrix is defined by a (multiline) block
-   of floats, with each line corresponding to a row. The number of columns
-   must be equal to :math:`2 l + 1`, with :math:`l` given by `LSHELL`. Only real matrices
-   are allowed. This parameter can be useful to select certain subset of
-   orbitals or perform a simple global rotation.
-*  **TRANSFILE** (string): name of the file containing transformation
-   matrices for each site. This option allows for a full-fledged functionality
-   when it comes to local state transformations. The format of this file
-   is described :ref:`below <transformation_file>`.
-
-Section [Group]
-"""""""""""""""
-
-Each defined projector shell must be part of a projector group. In the current
-implementation of DFTtools only a single group (labelled by any integer, e.g. `[Group 1]`)
-is supported. This implies that all projector shells
-must be included in this group.
-
-Required parameters for any group are the following:
-
-*  **SHELLS** (list of integers): indices of projector shells included in the group.
-   All defined shells must be grouped.
-*  **EWINDOW** (float float): the energy window specified by two floats: bottom
-   and top. All projectors in the current group are going to be normalized within
-   this window. *Note*: This option must be specified inside the `[Shell]` section
-   if only one shell is defined and the `[Group]` section is omitted.
-
-Optional group parameters:
-
-*  **NORMALIZE** (True/False): specifies whether projectors in the group are
-   to be normalized. The default value is **True**.
-*  **NORMION** (True/False): specifies whether projectors are normalized on
-   a per-site (per-ion) basis. That is, if `NORMION = True`, the orthogonality
-   condition will be enforced on each site separately but the Wannier functions
-   on different sites will not be orthogonal. If `NORMION = False`, the Wannier functions
-   on different sites included in the group will be orthogonal to each other.
-
-
-.. _transformation_file:
-
-File of transformation matrices
-"""""""""""""""""""""""""""""""
-
-.. warning::
-  The description below applies only to collinear cases (i.e., without spin-orbit
-  coupling). In this case, the matrices are spin-independent.
-
-The file specified by option `TRANSFILE` contains transformation matrices
-for each ion.  Each line must contain a series of floats whose number is either equal to
-the number of orbitals :math:`N_{orb}` (in this case the transformation matrices
-are assumed to be real) or to :math:`2 N_{orb}` (for the complex transformation matrices).
-The total number of lines :math:`N` must be a multiple of the number of ions :math:`N_{ion}`
-and the ratio :math:`N / N_{ion}`, then, gives the dimension of the transformed
-orbital space. The lines with floats can be separated by any number of empty or
-comment lines (starting from `#`), which are ignored.
-
-A very simple example is a transformation matrix that selects the :math:`t_{2g}` manifold.
-For two correlated sites, one can define the file as follows:
-::
-
-  # Site 1
-    1.0   0.0   0.0   0.0   0.0
-    0.0   1.0   0.0   0.0   0.0
-    0.0   0.0   0.0   1.0   0.0
-
-  # Site 2
-    1.0   0.0   0.0   0.0   0.0
-    0.0   1.0   0.0   0.0   0.0
-    0.0   0.0   0.0   1.0   0.0
-

doc/guide/soc.rst

@@ -0,0 +1,53 @@
+.. _soc:
+
+Spin-orbit coupled calculations (single-shot)
+=============================================
+
+There are two main ways of including the spin-orbit coupling (SOC) term into
+DFT+DMFT calculations:
+
+-   by performing a DFT calculation including SOC and then doing a DMFT calculation on top, or
+-   by performing a DFT calculation without SOC and then adding the SOC term on the model level.
+
+The second variant is a bit more involved and needs quite some expertise, so this guide will cover only the first variant with SOC included in the DFT calculations.
+
+Treatment of SOC in DFT
+-----------------------
+
+For now, TRIQS/DFTTools does only work with Wien2k and Elk when performing calculations with SO.
+The treatment of SOC in the VASP package is fundamentally different to the way Wien2k treats it, and the interface does not handle that at the moment.
+Therefore, this guide describes how to do an SOC calculation using the Wien2k and Elk DFT packages.
+
+Treatment of SOC in Wien2k
+--------------------------
+
+First, a Wien2k calculation including SOC has to be performed.
+For details, we refer the reader to the `documentation of Wien2k <http://susi.theochem.tuwien.ac.at/reg_user/textbooks/>`_ . As a matter of fact, we need the output for the DFT band structure for both spin directions explicitly. That means that one needs to do a spin-polarised DFT calculation with SOC, but, however, with magnetic moment set to zero. In the Wien2k initialisation procedure, one can choose for the option -nom when ``lstart`` is called. This means that the charge densities are initialised without magnetic splitting. The SOC calculation is then performed in a standard way as described in the Wien2k manual.
+
+Performing the projection in Wien2k
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that the final ``x lapw2 -almd -so -up`` and ``x lapw2 -almd -so -dn`` have to be run *on a single core*, which implies that, before, ``x lapw2 -up``, ``x lapw2 -dn``, and ``x lapwso -up`` have to be run in single-core mode (at least once).
+
+In the ``case.indmftpr`` file, the spin-orbit flag has to be set to ``1`` for the correlated atoms.
+For example, for the compound Sr\ :sub:`2`\ MgOsO\ :sub:`6`, with the struct file :download:`Sr2MgOsO6.struct <Sr2MgOsO6/Sr2MgOsO6.struct>`, we would, e.g., use the ``indmftpr`` file :download:`found here <Sr2MgOsO6/Sr2MgOsO6_SOC.indmftpr>`.
+Then, ``dmftproj -sp -so`` has to be called.
+As usual, it is important to check for warnings (e.g., about eigenvalues of the overlap matrix) in the output of ``dmftproj`` and adapt the window until these warnings disappear.
+
+Note that in presence of SOC, it is not possible to project only onto the :math:`t_{2g}` subshell because it is not an irreducible representation.
+
+Treatment of SOC in Elk
+-------------------------
+
+First, a Elk calculation including SOC has to be performed. For details, we refer the reader to the SOC Elk examples in Elk's example directory and `Elk manual <https//elk.sourceforge.net/elk.pdf>`_ for further information about the input flags. Then the projectors can be generated using the ``wanproj`` input flag in the same format as in :ref:`convElk`. Like in Wien2k, you cannot project only onto the :math:`t_{2g}` subshell because it is not an irreducible representation in SOC calculations. 
+
+After generating the projectors
+-------------------------------
+
+We strongly suggest using the :py:meth:`.dos_wannier_basis` functionality of the :py:class:`.SumkDFTTools` class (see :download:`calculate_dos_wannier_basis.py <Sr2RuO4/calculate_dos_wannier_basis.py>`) and compare the Wannier-projected orbitals to the original DFT DOS (they should be more or less equal).
+Note that, with SOC, there are usually off-diagonal elements of the spectral function, which can also be imaginary.
+The imaginary part can be found in the third column of the files ``DOS_wann_...``.
+
+After the projection, one can proceed with the DMFT calculation. However, two things need to be noted here. First, since the spin is not a good quantum number any more, there are off-diagonal elements in the hybridisation function and the local Hamiltonian coupling the two spin directions. This will eventually lead to a fermonic sign problem when QMC is used as a impurity solver. Second, although the :math:`e_{g}` subshell needs to be included in the projection, it can in many cases be neglected in the solution of the Anderson impurity model, after a transformation to a rotated local basis is done. This basis, diagonalising the local Hamiltonian in the presence of SOC, is often called the numerical j-basis. How rotations are performed is described in :ref:`basisrotation`, and the cutting of the orbitals in :ref:`blockstructure`.
+
+A DMFT calculation including SOC for Sr2MgOsO6 using Wien2k is included in the :ref:`tutorials`.

doc/guide/transport.rst

@@ -52,13 +52,13 @@ real-frequency self energy.
   it is crucial to perform the analytic continuation in such a way that the real-frequency self energy
   is accurate around the Fermi energy as low-energy features strongly influence the final results.
 
-Besides the self energy the Wien2k files read by the transport converter (:meth:`convert_transport_input <dft.converters.wien2k_converter.Wien2kConverter.convert_transport_input>`) are:
+Besides the self energy the Wien2k files read by the transport converter (:meth:`convert_transport_input <dft.converters.wien2k.Wien2kConverter.convert_transport_input>`) are:
    * :file:`.struct`: The lattice constants specified in the struct file are used to calculate the unit cell volume.
    * :file:`.outputs`: In this file the k-point symmetries are given.
    * :file:`.oubwin`: Contains the indices of the bands within the projected subspace (written by :program:`dmftproj`) for each k-point.
    * :file:`.pmat`: This file is the output of the Wien2k optics package and contains the velocity (momentum) matrix elements between all bands in the desired energy
      window for each k-point. How to use the optics package is described below.
-   * :file:`.h5`: The hdf5 archive has to be present and should contain the dft_input subgroup. Otherwise :meth:`convert_dft_input <dft.converters.wien2k_converter.Wien2kConverter.convert_dft_input>` needs to be called before :meth:`convert_transport_input <dft.converters.wien2k_converter.Wien2kConverter.convert_transport_input>`.
+   * :file:`.h5`: The hdf5 archive has to be present and should contain the dft_input subgroup. Otherwise :meth:`convert_dft_input <dft.converters.wien2k.Wien2kConverter.convert_dft_input>` needs to be called before :meth:`convert_transport_input <dft.converters.wien2k.Wien2kConverter.convert_transport_input>`.
 
 
 Wien2k optics package
@@ -84,7 +84,7 @@ Using the transport code
 
 First we have to read the Wien2k files and store the relevant information in the hdf5 archive::
 
-    from triqs_dft_tools.converters.wien2k_converter import *
+    from triqs_dft_tools.converters.wien2k import *
     from triqs_dft_tools.sumk_dft_tools import *
 
     Converter = Wien2kConverter(filename='case', repacking=True)
@@ -92,7 +92,7 @@ First we have to read the Wien2k files and store the relevant information in the
 
     SK = SumkDFTTools(hdf_file='case.h5', use_dft_blocks=True)
 
-The converter :meth:`convert_transport_input <dft.converters.wien2k_converter.Wien2kConverter.convert_transport_input>`
+The converter :meth:`convert_transport_input <dft.converters.wien2k.Wien2kConverter.convert_transport_input>`
 reads the required data of the Wien2k output and stores it in the `dft_transp_input` subgroup of your hdf file. 
 Additionally we need to read and set the self energy, the chemical potential and the double counting::
 

doc/h5structure.rst

@@ -1,12 +1,12 @@
 .. _hdfstructure:
 
-hdf5 structure
-==============
+standardized hdf5 structure
+===========================
 
-All the data is stored using the hdf5 standard, as described also in the
+All the DFT input data is stored using the hdf5 standard, as described also in the
 documentation of the TRIQS package itself. In order to do a DMFT calculation,
 using input from DFT applications, a converter is needed on order to provide
-the necessary data in the hdf5 format. 
+the necessary data in the hdf5 format.
 
 groups and their formats
 ------------------------
@@ -17,7 +17,7 @@ DMFT calculations for all kinds of situations, e.g. d-p Hamiltonians, more than
 one correlated atomic shell, or using symmetry operations for the k-summation.
 We store all data in subgroups of the hdf5 archive:
 
-Main data 
+Main data
 ^^^^^^^^^
 There needs to be one subgroup for the main data of the
 calculation. The default name of this group is `dft_input`. Its contents are
@@ -31,56 +31,94 @@ k_dep_projection   numpy.int
                                                                                            0 otherwise.
 SP                 numpy.int                                                               1 for spin-polarised Hamiltonian, 0 for paramagnetic Hamiltonian.
 SO                 numpy.int                                                               1 if spin-orbit interaction is included, 0 otherwise.
-charge_below       numpy.float                                                             Number of electrons in the crystal below the correlated orbitals. 
-                                                                                           Note that this is for compatibility with dmftproj.
+charge_below       numpy.float                                                             Number of electrons in the crystal below the correlated orbitals.
+                                                                                           Note that this is for compatibility with dmftproj, otherwise set to 0
 density_required   numpy.float                                                             Required total electron density. Needed to determine the chemical potential.
                                                                                            The density in the projection window is then `density_required`-`charge_below`.
-symm_op            numpy.int                                                               1 if symmetry operations are used for the BZ sums, 
+symm_op            numpy.int                                                               1 if symmetry operations are used for the BZ sums,
                                                                                            0 if all k-points are directly included in the input.
-n_shells           numpy.int                                                               Number of atomic shells for which post-processing is possible. 
-                                                                                           Note: this is `not` the number of correlated orbitals! 
+n_shells           numpy.int                                                               Number of atomic shells for which post-processing is possible.
+                                                                                           Note: this is `not` the number of correlated orbitals!
                                                                                            If there are two equivalent atoms in the unit cell, `n_shells` is 2.
-shells             list of dict {string:int}, dim n_shells x 4                             Atomic shell information. 
-                                                                                           For each shell, have a dict with keys ['atom', 'sort', 'l', 'dim']. 
+shells             list of dict {string:int}, dim n_shells x 4                             Atomic shell information.
+                                                                                           For each shell, have a dict with keys ['atom', 'sort', 'l', 'dim'].
                                                                                            'atom' is the atom index, 'sort' defines the equivalency of the atoms,
                                                                                            'l' is the angular quantum number, 'dim' is the dimension of the atomic shell.
-                                                                                           e.g. for two equivalent atoms in the unit cell, `atom` runs from 0 to 1, 
+                                                                                           e.g. for two equivalent atoms in the unit cell, `atom` runs from 0 to 1,
                                                                                            but `sort` can take only one value 0.
-n_corr_shells      numpy.int                                                               Number of correlated atomic shells. 
-                                                                                           If there are two correlated equivalent atoms in the unit cell, `n_corr_shells` is 2. 
-corr_shells        list of dict {string:int}, dim n_corr_shells x 6                        Correlated orbital information. 
-                                                                                           For each correlated shell, have a dict with keys 
-                                                                                           ['atom', 'sort', 'l', 'dim', 'SO', 'irep']. 
+n_corr_shells      numpy.int                                                               Number of correlated atomic shells.
+                                                                                           If there are two correlated equivalent atoms in the unit cell, `n_corr_shells` is 2.
+n_inequiv_shells   numpy.int                                                               Number of inequivalent atomic shells. Needs to be smaller than `n_corr_shells`.
+                                                                                           The up / downfolding routines mediate between all correlated shells and the
+                                                                                           actual inequivalent shells, by using the self-energy etc. for all equal shells
+                                                                                           belonging to the same class of inequivalent shells. The mapping is performed with
+                                                                                           information stored in `corr_to_inequiv` and `inequiv_to_corr`.
+corr_to_inequiv    list of numpy.int, dim `n_corr_shells`                                  mapping from correlated shells to inequivalent correlated shells.
+                                                                                           A list of length `n_corr_shells` containing integers, where same numbers mark
+                                                                                           equivalent sites.
+inequiv_to_corr    list of numpy.int, dim `n_inequiv_shells`                               A list of length `n_inequiv_shells` containing list indices as integers pointing
+                                                                                           to the corresponding sites in `corr_to_inequiv`.
+corr_shells        list of dict {string:int}, dim n_corr_shells x 6                        Correlated orbital information.
+                                                                                           For each correlated shell, have a dict with keys
+                                                                                           ['atom', 'sort', 'l', 'dim', 'SO', 'irrep'].
                                                                                            'atom' is the atom index, 'sort' defines the equivalency of the atoms,
                                                                                            'l' is the angular quantum number, 'dim' is the dimension of the atomic shell.
                                                                                            'SO' is one if spin-orbit is included, 0 otherwise, 'irep' is a dummy integer 0.
 use_rotations      numpy.int                                                               1 if local and global coordinate systems are used, 0 otherwise.
-rot_mat            list of numpy.array.complex,                                            Rotation matrices for correlated shells, if `use_rotations`.  
-                   dim n_corr_shells x [corr_shells['dim'],corr_shells['dim']]             Set to the unity matrix if no rotations are used.             
+rot_mat            list of numpy.array.complex,                                            Rotation matrices for correlated shells, if `use_rotations`.
+                   dim n_corr_shells x [corr_shells['dim'],corr_shells['dim']]             These rotations are automatically applied for up / downfolding.
+                                                                                           Set to the unity matrix if no rotations are used.
 rot_mat_time_inv   list of numpy.int, dim n_corr_shells                                    If `SP` is 1, 1 if the coordinate transformation contains inversion, 0 otherwise.
                                                                                            If `use_rotations` or `SP` is 0, give a list of zeros.
-n_reps             numpy.int                                                               Number of irreducible representations of the correlated shell. 
+n_reps             numpy.int                                                               Number of irreducible representations of the correlated shell.
                                                                                            e.g. 2 if eg/t2g splitting is used.
 dim_reps           list of numpy.int, dim n_reps                                           Dimension of the representations.
-                                                                                           e.g. [2,3] for eg/t2g subsets. 
-T                  list of numpy.array.complex,                                            Transformation matrix from the spherical harmonics to impurity problem basis 
-                   dim n_inequiv_corr_shell x                                              normally the real cubic harmonics). 
-                   [max(corr_shell['dim']),max(corr_shell['dim'])]                         This matrix is used to calculate the 4-index U matrix.
+                                                                                           e.g. [2,3] for eg/t2g subsets.
+T                  list of numpy.array.complex,                                            Transformation matrix from the spherical harmonics to impurity problem basis
+                   dim n_inequiv_corr_shell x                                              normally the real cubic harmonics).
+                   [max(corr_shell['dim']),max(corr_shell['dim'])]                         This matrix can be used to calculate the 4-index U matrix, not automatically done.
 n_orbitals         numpy.array.int, dim [n_k,SP+1-SO]                                      Number of Bloch bands included in the projection window for each k-point.
                                                                                            If SP+1-SO=2, the number of included bands may depend on the spin projection up/down.
 proj_mat           numpy.array.complex,                                                    Projection matrices from Bloch bands to Wannier orbitals.
-                   dim [n_k,SP+1-SO,n_corr_shells,max(corr_shell['dim']),max(n_orbitals)]  For efficient storage reasons, all matrices must be of the same size 
-                                                                                           (given by last two indices). 
+                   dim [n_k,SP+1-SO,n_corr_shells,max(corr_shell['dim']),max(n_orbitals)]  For efficient storage reasons, all matrices must be of the same size
+                                                                                           (given by last two indices).
                                                                                            For k-points with fewer bands, only the first entries are used, the rest are zero.
                                                                                            e.g. if number of Bloch bands ranges from 4-6, all matrices are of size 6.
-bz_weights         numpy.array.float, dim n_k                                              Weights of the k-points for the k summation.
-hopping            numpy.array.complex,                                                    Non-interacting Hamiltonian matrix for each k point. 
-                   dim [n_k,SP+1-SO,max(n_orbitals),max(n_orbitals)]                       As for `proj_mat`, all matrices have to be of the same size. 
+bz_weights         numpy.array.float, dim n_k                                              Weights of the k-points for the k summation. Soon be replaced by `kpt_weights`
+hopping            numpy.array.complex,                                                    Non-interacting Hamiltonian matrix for each k point.
+                   dim [n_k,SP+1-SO,max(n_orbitals),max(n_orbitals)]                       As for `proj_mat`, all matrices have to be of the same size.
+=================  ======================================================================  =====================================================================================
+
+Converter specific data
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This data is specific to the different converters and stored in the `dft_input`
+group as well.
+
+For the Vasp converter:
+
+=================  ======================================================================  =====================================================================================
+Name               Type                                                                    Meaning
+=================  ======================================================================  =====================================================================================
+kpt_basis          numpy.array.float, dim [3, 3]                                           Basis for the k-point mesh, reciprocal lattice vectors.
+kpts               numpy.array.float, dim [n_k, 3]                                         k-points given in reciprocal coordinates.
+kpt_weights        numpy.array.float, dim [n_k]                                            Weights of the k-points for the k summation.
+proj_or_hk         string                                                                  Switch determining whether the Vasp converter is running in projection mode `proj`, or
+                                                                                           in Hamiltonian mode `hk`. In Hamiltonian mode, the hopping matrix is written in
+                                                                                           orbital basis, whereas in projection mode hopping is written in band basis.
+proj_mat_csc       numpy.array.complex,                                                    Projection matrices from Bloch bands to Wannier orbitals for Hamiltonian based `hk`
+                   dim                                                                     approach. No site index is given, since hk is written in orbital basis. The last to
+                   [n_k, SP+1-SO, n_corr_shells, max(corr_shell['dim']), max(n_orbitals)]  indices are a square matrix rotating from orbital to band space.
+dft_fermi_weights  numpy.array.float, dim [n_k, SP+1-SO, max(n_orbitals)]                  DFT fermi weights (occupations) of KS eigenstates for each k-point for calculation
+                   (stored in dft_misc_input)                                              of density matrix correction.
+band_window        list of numpy.array.int , dim [n_k, 2]                                  Band windows as KS band indices in Vasp for each spin channel, and k-point. Needed for
+                   (stored in dft_misc_input)                                              writing out the GAMMA file.
 =================  ======================================================================  =====================================================================================
 
 
+
 Symmetry operations
-^^^^^^^^^^^^^^^^^^^ 
+^^^^^^^^^^^^^^^^^^^
 In this subgroup we store all the data for applying the symmetry operations in
 the DMFT loop (in case you want to use symmetry operations). The default name
 of this subgroup is `dft_symmcorr_input`. This information is needed only if symmetry
@@ -127,8 +165,8 @@ It is furthermore assumed that all k-points have equal weight in the k-sum.
 Note that the input file should contain only the numbers, not the comments
 given in above example.
 
-The Hamiltonian matrices can be taken, e.g., from Wannier90, which contructs
-the Hamiltonian in a maximally localised Wannier basis.
+The Hamiltonian matrices can be taken, e.g., from Wannier90, which constructs
+the Hamiltonian in a maximally localized Wannier basis.
 
 Note that with this simplified converter, no full charge self consistent
 calculations are possible!

doc/index.rst

@@ -1,31 +1,68 @@
-.. index:: DFTTools
-
-.. module:: triqs_dft_tools
-
-.. _dft:
+.. _welcome: 
 
+#########
 DFTTools
-========
+#########
 
-.. sidebar:: DFTTools 2.2
+.. sidebar:: DFTTools 3.0.0
+
+   This is the homepage of DFTTools v3.0.0.
+   For changes see the :ref:`changelog page <changelog>`.
+      
+      .. image:: _static/logo_github.png
+         :width: 75%
+         :align: center
+         :target: https://github.com/triqs/dft_tools
 
-   This is the homepage DFTTools Version 2.2
-   For the changes in DFTTools, Cf :ref:`changelog page <changelog>`
 
 This :ref:`TRIQS-based <triqslibs:welcome>`-based application is aimed
 at ab-initio calculations for 
 correlated materials, combining realistic DFT band-structure
 calculations with the dynamical mean-field theory. Together with the
 necessary tools to perform the DMFT self-consistency loop for
-realistic multi-band problems, the package provides a full-fledged
+realistic multi-band problems. The package provides a full-fledged
 charge self-consistent interface to the `Wien2K package
-<http://www.wien2k.at>`_. In addition, if Wien2k is not available, it
-provides a generic interface for one-shot DFT+DMFT calculations, where
-only the single-particle Hamiltonian in orbital space has to be
-provided.
+<http://www.wien2k.at>`_, and `VASP package <https://www.vasp.at>`_. 
+In addition, it provides a generic interface for one-shot DFT+DMFT 
+calculations, where only the single-particle Hamiltonian in 
+orbital space has to be provided. The Hamiltonian can be  
+generated from the above mentioned DFT codes, 
+`wannier90 <http://www.wannier.org/>`_ output files, or with the 
+built-in generic H(k) converter.
 
 Learn how to use this package in the :ref:`documentation` and the :ref:`tutorials`.
 
+.. image:: _static/logo_cea.png
+   :width: 14%
+   :target: http://ipht.cea.fr
 
+.. image:: _static/logo_x.png
+   :width: 14%
+   :target: "https://www.cpht.polytechnique.fr
+
+.. image:: _static/logo_cnrs.png
+   :width: 14%
+   :target: https://www.cnrs.fr
+
+.. image:: _static/logo_erc.jpg
+   :width: 14%
+
+.. image:: _static/logo_flatiron.png
+   :width: 20%
+   :target: https://www.simonsfoundation.org/flatiron
+
+.. image:: _static/logo_simons.jpg
+   :width: 20%
+   :target: https://www.simonsfoundation.org
+
+    
 .. toctree::
    :maxdepth: 2
+   :hidden:
+
+   install
+   documentation
+   tutorials
+   issues
+   ChangeLog.md
+   about

doc/install.rst

@@ -2,16 +2,36 @@
 
 .. _install:
 
+Installation
+************
 
 Packaged Versions of DFTTools
 =============================
 
-A Docker image including the latest version of DFTTools is available `here <https://hub.docker.com/r/flatironinstitute/triqs>`_. For more information, please see the page on :ref:`TRIQS Docker <triqslibs:triqs_docker>`.
+.. _ubuntu_debian:
+Ubuntu Debian packages
+----------------------
 
-We further provide a Debian package for the Ubuntu LTS Versions 16.04 (xenial) and 18.04 (bionic), which can be installed by following the steps outlined :ref:`here <triqslibs:triqs_docker>`, and the subsequent command::
+We provide a Debian package for the Ubuntu LTS Versions 18.04 (bionic) and 20.04 (focal), which can be installed by following the steps outlined :ref:`here <triqslibs:ubuntu_debian>`, and the subsequent command::
 
         sudo apt-get install -y triqs_dft_tools
 
+.. _anaconda:
+Anaconda (experimental)
+-----------------------
+
+We provide Linux and OSX packages for the `Anaconda <https://www.anaconda.com/>`_ distribution. The packages are provided through the `conda-forge <https://conda-forge.org/>`_ repositories. After `installing conda <https://docs.conda.io/en/latest/miniconda.html>`_ you can install DFTTools with::
+
+        conda install -c conda-forge triqs_dft_tools
+
+See also `github.com/conda-forge/triqs_dft_tools-feedstock <https://github.com/conda-forge/triqs_dft_tools-feedstock/>`_.
+
+.. _docker:
+Docker
+------
+
+A Docker image including the latest version of DFTTools is available `here <https://hub.docker.com/r/flatironinstitute/triqs>`_. For more information, please see the page on :ref:`TRIQS Docker <triqslibs:triqs_docker>`.
+
 
 Compiling DFTTools from source
 ==============================
@@ -19,34 +39,40 @@ Compiling DFTTools from source
 Prerequisites
 -------------
 
-#. The :ref:`TRIQS <triqslibs:welcome>` toolbox. 
+#. The :ref:`TRIQS <triqslibs:welcome>` library, see :ref:`TRIQS installation instruction <triqslibs:triqs_install>`.
+   In the following, we assume that TRIQS is installed in the directory ``path_to_triqs``.
+#. Likely, you will also need at least one impurity solver, e.g. the `CTHYB solver <https://triqs.github.io/cthyb/latest/>`_.
 
-#. Likely, you will also need at least one impurity solver, e.g. the :ref:`CTHYB solver <triqscthyb:welcome>`.
-
-Installation steps 
+Installation steps
 ------------------
 
-#. Download the source code by cloning the ``TRIQS/dft_tools`` repository from GitHub::
- 
-     $ git clone https://github.com/TRIQS/dft_tools.git dft_tools.src
- 
+#. Download the source code of the latest stable version by cloning the ``TRIQS/dft_tools`` repository from GitHub::
+
+     $ git clone https://github.com/TRIQS/dft_tools dft_tools.src
+
 #. Create and move to a new directory where you will compile the code::
- 
+
      $ mkdir dft_tools.build && cd dft_tools.build
- 
+
 #. Ensure that your shell contains the TRIQS environment variables by sourcing the ``triqsvars.sh`` file from your TRIQS installation::
 
-     $ source path_to_triqs/share/triqsvarsh.sh
-     
+     $ source path_to_triqs/share/triqs/triqsvars.sh
+
 #. In the build directory call cmake, including any additional custom CMake options, see below::
 
      $ cmake ../dft_tools.src
- 
-#. Compile the code, run the tests and install the application:: 
- 
-     $ make 
-     $ make test 
-     $ make install 
+
+#. Compile the code, run the tests and install the application::
+
+     $ make
+     $ make test
+     $ make install
+
+
+Important note for FCSC DFT+DMFT calculations
+---------------------------------------------
+
+To use dft_tools together with any of the supported DFT codes (Wien2k, Vasp, or Elk) in a full charge self-consistent manner, please make sure to compile both triqs and the designated DFT code with the same compiler / library setup for best compatibility. For example, if Vasp is compiled with the intel compiler suite, it will not be possible to use it together with a GNU compiled triqs and vice versa during a FCSC calculation, as both codes need to run at the same time. Hence, it is highly advisable to not use the intel compilers (linking againt intel mkl libraries is of course fine) to compile any of the interfaced DFT codes.
 
 
 Installation steps for the use with WIEN2K version 14.2 and older
@@ -96,37 +122,41 @@ Finally, you will have to change the calls to :program:`python_with_DMFT` to
 your :program:`python` installation in the Wien2k :file:`path_to_Wien2k/run*` files.
 
  
-Version compatibility 
+Version compatibility
 ---------------------
- 
-Be careful that the version of the TRIQS library and of the :program:`DFTTools` must be
-compatible (more information on the :ref:`TRIQS website <triqslibs:welcome>`. 
-If you want to use a version of the :program:`DFTTools` that is not the latest one, go
-into the directory with the sources and look at all available versions:: 
- 
-     $ cd src && git tag 
- 
-Checkout the version of the code that you want, for instance:: 
- 
-     $ git co 2.1 
- 
-Then follow the steps 2 to 5 described above to compile the code. 
+
+Keep in mind that the version of ``dft_tools`` must be compatible with your TRIQS library version,
+see :ref:`TRIQS website <triqslibs:versions>`.
+In particular the Major and Minor Version numbers have to be the same.
+To use a particular version, go into the directory with the sources, and look at all available versions::
+
+     $ cd dft_tools.src && git tag
+
+Checkout the version of the code that you want::
+
+     $ git checkout 2.1.0
+
+and follow steps 2 to 4 above to compile the code.
 
 Custom CMake options
 --------------------
 
-Functionality of ``dft_tools`` can be tweaked using extra compile-time options passed to CMake::
+The compilation of ``dft_tools`` can be configured using CMake-options::
 
-    cmake -DOPTION1=value1 -DOPTION2=value2 ... ../dft_tools.src
+    cmake ../dft_tools.src -DOPTION1=value1 -DOPTION2=value2 ...
 
-+---------------------------------------------------------------+-----------------------------------------------+
-| Options                                                       | Syntax                                        |
-+===============================================================+===============================================+
-| Disable testing (not recommended)                             | -DBuild_Tests=OFF                             |
-+---------------------------------------------------------------+-----------------------------------------------+
-| Build the documentation locally                               | -DBuild_Documentation=ON                      |
-+---------------------------------------------------------------+-----------------------------------------------+
-| Check test coverage when testing                              | -DTEST_COVERAGE=ON                            |
-| (run ``make coverage`` to show the results; requires the      |                                               |
-| python ``coverage`` package)                                  |                                               |
-+---------------------------------------------------------------+-----------------------------------------------+
++-----------------------------------------------------------------+-----------------------------------------------+
+| Options                                                         | Syntax                                        |
++=================================================================+===============================================+
+| Specify an installation path other than path_to_triqs           | -DCMAKE_INSTALL_PREFIX=path_to_dft_tools      |
++-----------------------------------------------------------------+-----------------------------------------------+
+| Build in Debugging Mode                                         | -DCMAKE_BUILD_TYPE=Debug                      |
++-----------------------------------------------------------------+-----------------------------------------------+
+| Disable testing (not recommended)                               | -DBuild_Tests=OFF                             |
++-----------------------------------------------------------------+-----------------------------------------------+
+| Build the documentation                                         | -DBuild_Documentation=ON                      |
++-----------------------------------------------------------------+-----------------------------------------------+
+| Check test coverage when testing                                | -DTEST_COVERAGE=ON                            |
+| (run ``make coverage`` to show the results; requires the        |                                               |
+| python ``coverage`` package)                                    |                                               |
++-----------------------------------------------------------------+-----------------------------------------------+

doc/issues.rst

@@ -1,13 +1,14 @@
+.. _issues:
 
 Reporting issues
-================
+*****************
 
 Please report all problems and bugs directly at the github issue page
-`<https://github.com/TRIQS/dft_tools/issues>`_.  In order to make it easier
-for us to solve the issue please follow these guidelines:
+`<https://github.com/TRIQS/dft_tools/issues>`_.  In order to make it easier for us
+to solve the issue please follow these guidelines:
 
 #. In all cases specify which version of the application you are using. You can
-   find the version number in the file :file:`README.txt` at the root of the
+   find the version number in the file :file:`CMakeLists.txt` at the root of the
    application sources.
 
 #. If you have a problem during the installation, give us information about

doc/reference/block_structure.rst

@@ -1,22 +0,0 @@
-Block Structure
-===============
-
-The `BlockStructure` class allows to change and manipulate
-Green functions structures and mappings from sumk to solver.
-
-The block structure can also be written to and read from HDF files.
-
-.. warning::
-
-    Do not write the individual elements of this class to a HDF file,
-    as they belong together and changing one without the other can 
-    result in unexpected results. Always write the BlockStructure 
-    object as a whole.
-
-    Writing the sumk_to_solver and solver_to_sumk elements
-    individually is not implemented.
-
-.. autoclass:: triqs_dft_tools.block_structure.BlockStructure
-   :members:
-   :show-inheritance:
-   

doc/reference/converters.rst

@@ -1,29 +0,0 @@
-.. _refconverters:
-
-Converters
-==========
-
-Wien2k Converter
-----------------
-.. autoclass:: triqs_dft_tools.converters.wien2k_converter.Wien2kConverter
-   :members:
-   :special-members:
-   :show-inheritance:
-
-H(k) Converter
---------------
-.. autoclass:: triqs_dft_tools.converters.hk_converter.HkConverter
-   :members:
-   :special-members:
-
-Wannier90 Converter
--------------------
-.. autoclass:: triqs_dft_tools.converters.wannier90_converter.Wannier90Converter
-   :members:
-   :special-members:
-
-Converter Tools
----------------
-.. autoclass:: triqs_dft_tools.converters.converter_tools.ConverterTools
-   :members:
-   :special-members:

doc/reference/sumk_dft.rst

@@ -1,8 +0,0 @@
-SumK DFT
-========
-
-
-.. autoclass:: triqs_dft_tools.sumk_dft.SumkDFT
-   :members:
-   :special-members:
-   :show-inheritance:

doc/reference/sumk_dft_tools.rst

@@ -1,8 +0,0 @@
-SumK DFT Tools
-==============
-
-
-.. autoclass:: triqs_dft_tools.sumk_dft_tools.SumkDFTTools
-   :members:
-   :special-members:
-   :show-inheritance:

doc/reference/symmetry.rst

@@ -1,6 +0,0 @@
-Symmetry
-========
-
-.. autoclass:: triqs_dft_tools.Symmetry
-   :members:
-   :special-members:

doc/reference/transbasis.rst

@@ -1,6 +0,0 @@
-TransBasis
-==========
-
-.. autoclass:: triqs_dft_tools.trans_basis.TransBasis
-   :members:
-   :special-members:

doc/sphinxext/numpydoc/apigen.py

@@ -0,0 +1,427 @@
+"""Attempt to generate templates for module reference with Sphinx
+
+XXX - we exclude extension modules
+
+To include extension modules, first identify them as valid in the
+``_uri2path`` method, then handle them in the ``_parse_module`` script.
+
+We get functions and classes by parsing the text of .py files.
+Alternatively we could import the modules for discovery, and we'd have
+to do that for extension modules.  This would involve changing the
+``_parse_module`` method to work via import and introspection, and
+might involve changing ``discover_modules`` (which determines which
+files are modules, and therefore which module URIs will be passed to
+``_parse_module``).
+
+NOTE: this is a modified version of a script originally shipped with the
+PyMVPA project, which we've adapted for NIPY use.  PyMVPA is an MIT-licensed
+project."""
+
+# Stdlib imports
+import os
+import re
+
+# Functions and classes
+class ApiDocWriter:
+    ''' Class for automatic detection and parsing of API docs
+    to Sphinx-parsable reST format'''
+
+    # only separating first two levels
+    rst_section_levels = ['*', '=', '-', '~', '^']
+
+    def __init__(self,
+                 package_name,
+                 rst_extension='.rst',
+                 package_skip_patterns=None,
+                 module_skip_patterns=None,
+                 ):
+        ''' Initialize package for parsing
+
+        Parameters
+        ----------
+        package_name : string
+            Name of the top-level package.  *package_name* must be the
+            name of an importable package
+        rst_extension : string, optional
+            Extension for reST files, default '.rst'
+        package_skip_patterns : None or sequence of {strings, regexps}
+            Sequence of strings giving URIs of packages to be excluded
+            Operates on the package path, starting at (including) the
+            first dot in the package path, after *package_name* - so,
+            if *package_name* is ``sphinx``, then ``sphinx.util`` will
+            result in ``.util`` being passed for earching by these
+            regexps.  If is None, gives default. Default is:
+            ['\.tests$']
+        module_skip_patterns : None or sequence
+            Sequence of strings giving URIs of modules to be excluded
+            Operates on the module name including preceding URI path,
+            back to the first dot after *package_name*.  For example
+            ``sphinx.util.console`` results in the string to search of
+            ``.util.console``
+            If is None, gives default. Default is:
+            ['\.setup$', '\._']
+        '''
+        if package_skip_patterns is None:
+            package_skip_patterns = ['\\.tests$']
+        if module_skip_patterns is None:
+            module_skip_patterns = ['\\.setup$', '\\._']
+        self.package_name = package_name
+        self.rst_extension = rst_extension
+        self.package_skip_patterns = package_skip_patterns
+        self.module_skip_patterns = module_skip_patterns
+
+    def get_package_name(self):
+        return self._package_name
+
+    def set_package_name(self, package_name):
+        ''' Set package_name
+
+        >>> docwriter = ApiDocWriter('sphinx')
+        >>> import sphinx
+        >>> docwriter.root_path == sphinx.__path__[0]
+        True
+        >>> docwriter.package_name = 'docutils'
+        >>> import docutils
+        >>> docwriter.root_path == docutils.__path__[0]
+        True
+        '''
+        # It's also possible to imagine caching the module parsing here
+        self._package_name = package_name
+        self.root_module = __import__(package_name)
+        self.root_path = self.root_module.__path__[0]
+        self.written_modules = None
+
+    package_name = property(get_package_name, set_package_name, None,
+                            'get/set package_name')
+
+    def _get_object_name(self, line):
+        ''' Get second token in line
+        >>> docwriter = ApiDocWriter('sphinx')
+        >>> docwriter._get_object_name("  def func():  ")
+        'func'
+        >>> docwriter._get_object_name("  class Klass:  ")
+        'Klass'
+        >>> docwriter._get_object_name("  class Klass:  ")
+        'Klass'
+        '''
+        name = line.split()[1].split('(')[0].strip()
+        # in case we have classes which are not derived from object
+        # ie. old style classes
+        return name.rstrip(':')
+
+    def _uri2path(self, uri):
+        ''' Convert uri to absolute filepath
+
+        Parameters
+        ----------
+        uri : string
+            URI of python module to return path for
+
+        Returns
+        -------
+        path : None or string
+            Returns None if there is no valid path for this URI
+            Otherwise returns absolute file system path for URI
+
+        Examples
+        --------
+        >>> docwriter = ApiDocWriter('sphinx')
+        >>> import sphinx
+        >>> modpath = sphinx.__path__[0]
+        >>> res = docwriter._uri2path('sphinx.builder')
+        >>> res == os.path.join(modpath, 'builder.py')
+        True
+        >>> res = docwriter._uri2path('sphinx')
+        >>> res == os.path.join(modpath, '__init__.py')
+        True
+        >>> docwriter._uri2path('sphinx.does_not_exist')
+
+        '''
+        if uri == self.package_name:
+            return os.path.join(self.root_path, '__init__.py')
+        path = uri.replace('.', os.path.sep)
+        path = path.replace(self.package_name + os.path.sep, '')
+        path = os.path.join(self.root_path, path)
+        # XXX maybe check for extensions as well?
+        if os.path.exists(path + '.py'): # file
+            path += '.py'
+        elif os.path.exists(os.path.join(path, '__init__.py')):
+            path = os.path.join(path, '__init__.py')
+        else:
+            return None
+        return path
+
+    def _path2uri(self, dirpath):
+        ''' Convert directory path to uri '''
+        relpath = dirpath.replace(self.root_path, self.package_name)
+        if relpath.startswith(os.path.sep):
+            relpath = relpath[1:]
+        return relpath.replace(os.path.sep, '.')
+
+    def _parse_module(self, uri):
+        ''' Parse module defined in *uri* '''
+        filename = self._uri2path(uri)
+        if filename is None:
+            # nothing that we could handle here.
+            return ([],[])
+        f = open(filename, 'rt')
+        functions, classes = self._parse_lines(f)
+        f.close()
+        return functions, classes
+    
+    def _parse_lines(self, linesource):
+        ''' Parse lines of text for functions and classes '''
+        functions = []
+        classes = []
+        for line in linesource:
+            if line.startswith('def ') and line.count('('):
+                # exclude private stuff
+                name = self._get_object_name(line)
+                if not name.startswith('_'):
+                    functions.append(name)
+            elif line.startswith('class '):
+                # exclude private stuff
+                name = self._get_object_name(line)
+                if not name.startswith('_'):
+                    classes.append(name)
+            else:
+                pass
+        functions.sort()
+        classes.sort()
+        return functions, classes
+
+    def generate_api_doc(self, uri):
+        '''Make autodoc documentation template string for a module
+
+        Parameters
+        ----------
+        uri : string
+            python location of module - e.g 'sphinx.builder'
+
+        Returns
+        -------
+        S : string
+            Contents of API doc
+        '''
+        # get the names of all classes and functions
+        functions, classes = self._parse_module(uri)
+        if not len(functions) and not len(classes):
+            print('WARNING: Empty -',uri)  # dbg
+            return ''
+
+        # Make a shorter version of the uri that omits the package name for
+        # titles 
+        uri_short = re.sub(r'^%s\.' % self.package_name,'',uri)
+        
+        ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
+
+        chap_title = uri_short
+        ad += (chap_title+'\n'+ self.rst_section_levels[1] * len(chap_title)
+               + '\n\n')
+
+        # Set the chapter title to read 'module' for all modules except for the
+        # main packages
+        if '.' in uri:
+            title = 'Module: :mod:`' + uri_short + '`'
+        else:
+            title = ':mod:`' + uri_short + '`'
+        ad += title + '\n' + self.rst_section_levels[2] * len(title)
+
+        if len(classes):
+            ad += '\nInheritance diagram for ``%s``:\n\n' % uri
+            ad += '.. inheritance-diagram:: %s \n' % uri
+            ad += '   :parts: 3\n'
+
+        ad += '\n.. automodule:: ' + uri + '\n'
+        ad += '\n.. currentmodule:: ' + uri + '\n'
+        multi_class = len(classes) > 1
+        multi_fx = len(functions) > 1
+        if multi_class:
+            ad += '\n' + 'Classes' + '\n' + \
+                  self.rst_section_levels[2] * 7 + '\n'
+        elif len(classes) and multi_fx:
+            ad += '\n' + 'Class' + '\n' + \
+                  self.rst_section_levels[2] * 5 + '\n'
+        for c in classes:
+            ad += '\n:class:`' + c + '`\n' \
+                  + self.rst_section_levels[multi_class + 2 ] * \
+                  (len(c)+9) + '\n\n'
+            ad += '\n.. autoclass:: ' + c + '\n'
+            # must NOT exclude from index to keep cross-refs working
+            ad += '  :members:\n' \
+                  '  :undoc-members:\n' \
+                  '  :show-inheritance:\n' \
+                  '  :inherited-members:\n' \
+                  '\n' \
+                  '  .. automethod:: __init__\n'
+        if multi_fx:
+            ad += '\n' + 'Functions' + '\n' + \
+                  self.rst_section_levels[2] * 9 + '\n\n'
+        elif len(functions) and multi_class:
+            ad += '\n' + 'Function' + '\n' + \
+                  self.rst_section_levels[2] * 8 + '\n\n'
+        for f in functions:
+            # must NOT exclude from index to keep cross-refs working
+            ad += '\n.. autofunction:: ' + uri + '.' + f + '\n\n'
+        return ad
+
+    def _survives_exclude(self, matchstr, match_type):
+        ''' Returns True if *matchstr* does not match patterns
+
+        ``self.package_name`` removed from front of string if present
+
+        Examples
+        --------
+        >>> dw = ApiDocWriter('sphinx')
+        >>> dw._survives_exclude('sphinx.okpkg', 'package')
+        True
+        >>> dw.package_skip_patterns.append('^\\.badpkg$')
+        >>> dw._survives_exclude('sphinx.badpkg', 'package')
+        False
+        >>> dw._survives_exclude('sphinx.badpkg', 'module')
+        True
+        >>> dw._survives_exclude('sphinx.badmod', 'module')
+        True
+        >>> dw.module_skip_patterns.append('^\\.badmod$')
+        >>> dw._survives_exclude('sphinx.badmod', 'module')
+        False
+        '''
+        if match_type == 'module':
+            patterns = self.module_skip_patterns
+        elif match_type == 'package':
+            patterns = self.package_skip_patterns
+        else:
+            raise ValueError('Cannot interpret match type "%s"' 
+                             % match_type)
+        # Match to URI without package name
+        L = len(self.package_name)
+        if matchstr[:L] == self.package_name:
+            matchstr = matchstr[L:]
+        for pat in patterns:
+            try:
+                pat.search
+            except AttributeError:
+                pat = re.compile(pat)
+            if pat.search(matchstr):
+                return False
+        return True
+
+    def discover_modules(self):
+        ''' Return module sequence discovered from ``self.package_name`` 
+
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        mods : sequence
+            Sequence of module names within ``self.package_name``
+
+        Examples
+        --------
+        >>> dw = ApiDocWriter('sphinx')
+        >>> mods = dw.discover_modules()
+        >>> 'sphinx.util' in mods
+        True
+        >>> dw.package_skip_patterns.append('\.util$')
+        >>> 'sphinx.util' in dw.discover_modules()
+        False
+        >>> 
+        '''
+        modules = [self.package_name]
+        # raw directory parsing
+        for dirpath, dirnames, filenames in os.walk(self.root_path):
+            # Check directory names for packages
+            root_uri = self._path2uri(os.path.join(self.root_path,
+                                                   dirpath))
+            for dirname in dirnames[:]: # copy list - we modify inplace
+                package_uri = '.'.join((root_uri, dirname))
+                if (self._uri2path(package_uri) and
+                    self._survives_exclude(package_uri, 'package')):
+                    modules.append(package_uri)
+                else:
+                    dirnames.remove(dirname)
+            # Check filenames for modules
+            for filename in filenames:
+                module_name = filename[:-3]
+                module_uri = '.'.join((root_uri, module_name))
+                if (self._uri2path(module_uri) and
+                    self._survives_exclude(module_uri, 'module')):
+                    modules.append(module_uri)
+        return sorted(modules)
+    
+    def write_modules_api(self, modules,outdir):
+        # write the list
+        written_modules = []
+        for m in modules:
+            api_str = self.generate_api_doc(m)
+            if not api_str:
+                continue
+            # write out to file
+            outfile = os.path.join(outdir,
+                                   m + self.rst_extension)
+            fileobj = open(outfile, 'wt')
+            fileobj.write(api_str)
+            fileobj.close()
+            written_modules.append(m)
+        self.written_modules = written_modules
+
+    def write_api_docs(self, outdir):
+        """Generate API reST files.
+
+        Parameters
+        ----------
+        outdir : string
+            Directory name in which to store files
+            We create automatic filenames for each module
+            
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        Sets self.written_modules to list of written modules
+        """
+        if not os.path.exists(outdir):
+            os.mkdir(outdir)
+        # compose list of modules
+        modules = self.discover_modules()
+        self.write_modules_api(modules,outdir)
+        
+    def write_index(self, outdir, froot='gen', relative_to=None):
+        """Make a reST API index file from written files
+
+        Parameters
+        ----------
+        path : string
+            Filename to write index to
+        outdir : string
+            Directory to which to write generated index file
+        froot : string, optional
+            root (filename without extension) of filename to write to
+            Defaults to 'gen'.  We add ``self.rst_extension``.
+        relative_to : string
+            path to which written filenames are relative.  This
+            component of the written file path will be removed from
+            outdir, in the generated index.  Default is None, meaning,
+            leave path as it is.
+        """
+        if self.written_modules is None:
+            raise ValueError('No modules written')
+        # Get full filename path
+        path = os.path.join(outdir, froot+self.rst_extension)
+        # Path written into index is relative to rootpath
+        if relative_to is not None:
+            relpath = outdir.replace(relative_to + os.path.sep, '')
+        else:
+            relpath = outdir
+        idx = open(path,'wt')
+        w = idx.write
+        w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
+        w('.. toctree::\n\n')
+        for f in self.written_modules:
+            w('   %s\n' % os.path.join(relpath,f))
+        idx.close()

doc/sphinxext/numpydoc/docscrape.py

@@ -0,0 +1,497 @@
+"""Extract reference documentation from the NumPy source tree.
+
+"""
+
+import inspect
+import textwrap
+import re
+import pydoc
+from io import StringIO
+from warnings import warn
+4
+class Reader:
+    """A line-based string reader.
+
+    """
+    def __init__(self, data):
+        """
+        Parameters
+        ----------
+        data : str
+           String with lines separated by '\n'.
+
+        """
+        if isinstance(data,list):
+            self._str = data
+        else:
+            self._str = data.split('\n') # store string as list of lines
+
+        self.reset()
+
+    def __getitem__(self, n):
+        return self._str[n]
+
+    def reset(self):
+        self._l = 0 # current line nr
+
+    def read(self):
+        if not self.eof():
+            out = self[self._l]
+            self._l += 1
+            return out
+        else:
+            return ''
+
+    def seek_next_non_empty_line(self):
+        for l in self[self._l:]:
+            if l.strip():
+                break
+            else:
+                self._l += 1
+
+    def eof(self):
+        return self._l >= len(self._str)
+
+    def read_to_condition(self, condition_func):
+        start = self._l
+        for line in self[start:]:
+            if condition_func(line):
+                return self[start:self._l]
+            self._l += 1
+            if self.eof():
+                return self[start:self._l+1]
+        return []
+
+    def read_to_next_empty_line(self):
+        self.seek_next_non_empty_line()
+        def is_empty(line):
+            return not line.strip()
+        return self.read_to_condition(is_empty)
+
+    def read_to_next_unindented_line(self):
+        def is_unindented(line):
+            return (line.strip() and (len(line.lstrip()) == len(line)))
+        return self.read_to_condition(is_unindented)
+
+    def peek(self,n=0):
+        if self._l + n < len(self._str):
+            return self[self._l + n]
+        else:
+            return ''
+
+    def is_empty(self):
+        return not ''.join(self._str).strip()
+
+
+class NumpyDocString:
+    def __init__(self,docstring):
+        docstring = textwrap.dedent(docstring).split('\n')
+
+        self._doc = Reader(docstring)
+        self._parsed_data = {
+            'Signature': '',
+            'Summary': [''],
+            'Extended Summary': [],
+            'Parameters': [],
+            'Returns': [],
+            'Raises': [],
+            'Warns': [],
+            'Other Parameters': [],
+            'Attributes': [],
+            'Methods': [],
+            'See Also': [],
+            'Notes': [],
+            'Warnings': [],
+            'References': '',
+            'Examples': '',
+            'index': {}
+            }
+
+        self._parse()
+
+    def __getitem__(self,key):
+        return self._parsed_data[key]
+
+    def __setitem__(self,key,val):
+        if key not in self._parsed_data:
+            warn("Unknown section %s" % key)
+        else:
+            self._parsed_data[key] = val
+
+    def _is_at_section(self):
+        self._doc.seek_next_non_empty_line()
+
+        if self._doc.eof():
+            return False
+
+        l1 = self._doc.peek().strip()  # e.g. Parameters
+
+        if l1.startswith('.. index::'):
+            return True
+
+        l2 = self._doc.peek(1).strip() #    ---------- or ==========
+        return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
+
+    def _strip(self,doc):
+        i = 0
+        j = 0
+        for i,line in enumerate(doc):
+            if line.strip(): break
+
+        for j,line in enumerate(doc[::-1]):
+            if line.strip(): break
+
+        return doc[i:len(doc)-j]
+
+    def _read_to_next_section(self):
+        section = self._doc.read_to_next_empty_line()
+
+        while not self._is_at_section() and not self._doc.eof():
+            if not self._doc.peek(-1).strip(): # previous line was empty
+                section += ['']
+
+            section += self._doc.read_to_next_empty_line()
+
+        return section
+
+    def _read_sections(self):
+        while not self._doc.eof():
+            data = self._read_to_next_section()
+            name = data[0].strip()
+
+            if name.startswith('..'): # index section
+                yield name, data[1:]
+            elif len(data) < 2:
+                yield StopIteration
+            else:
+                yield name, self._strip(data[2:])
+
+    def _parse_param_list(self,content):
+        r = Reader(content)
+        params = []
+        while not r.eof():
+            header = r.read().strip()
+            if ' : ' in header:
+                arg_name, arg_type = header.split(' : ')[:2]
+            else:
+                arg_name, arg_type = header, ''
+
+            desc = r.read_to_next_unindented_line()
+            desc = dedent_lines(desc)
+
+            params.append((arg_name,arg_type,desc))
+
+        return params
+
+    
+    _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
+                           r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
+    def _parse_see_also(self, content):
+        """
+        func_name : Descriptive text
+            continued text
+        another_func_name : Descriptive text
+        func_name1, func_name2, :meth:`func_name`, func_name3
+
+        """
+        items = []
+
+        def parse_item_name(text):
+            """Match ':role:`name`' or 'name'"""
+            m = self._name_rgx.match(text)
+            if m:
+                g = m.groups()
+                if g[1] is None:
+                    return g[3], None
+                else:
+                    return g[2], g[1]
+            raise ValueError("%s is not a item name" % text)
+
+        def push_item(name, rest):
+            if not name:
+                return
+            name, role = parse_item_name(name)
+            items.append((name, list(rest), role))
+            del rest[:]
+
+        current_func = None
+        rest = []
+        
+        for line in content:
+            if not line.strip(): continue
+
+            m = self._name_rgx.match(line)
+            if m and line[m.end():].strip().startswith(':'):
+                push_item(current_func, rest)
+                current_func, line = line[:m.end()], line[m.end():]
+                rest = [line.split(':', 1)[1].strip()]
+                if not rest[0]:
+                    rest = []
+            elif not line.startswith(' '):
+                push_item(current_func, rest)
+                current_func = None
+                if ',' in line:
+                    for func in line.split(','):
+                        push_item(func, [])
+                elif line.strip():
+                    current_func = line
+            elif current_func is not None:
+                rest.append(line.strip())
+        push_item(current_func, rest)
+        return items
+
+    def _parse_index(self, section, content):
+        """
+        .. index: default
+           :refguide: something, else, and more
+
+        """
+        def strip_each_in(lst):
+            return [s.strip() for s in lst]
+
+        out = {}
+        section = section.split('::')
+        if len(section) > 1:
+            out['default'] = strip_each_in(section[1].split(','))[0]
+        for line in content:
+            line = line.split(':')
+            if len(line) > 2:
+                out[line[1]] = strip_each_in(line[2].split(','))
+        return out
+    
+    def _parse_summary(self):
+        """Grab signature (if given) and summary"""
+        if self._is_at_section():
+            return
+
+        summary = self._doc.read_to_next_empty_line()
+        summary_str = " ".join([s.strip() for s in summary]).strip()
+        if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
+            self['Signature'] = summary_str
+            if not self._is_at_section():
+                self['Summary'] = self._doc.read_to_next_empty_line()
+        else:
+            self['Summary'] = summary
+
+        if not self._is_at_section():
+            self['Extended Summary'] = self._read_to_next_section()
+    
+    def _parse(self):
+        self._doc.reset()
+        self._parse_summary()
+
+        for (section,content) in self._read_sections():
+            if not section.startswith('..'):
+                section = ' '.join([s.capitalize() for s in section.split(' ')])
+            if section in ('Parameters', 'Attributes', 'Methods',
+                           'Returns', 'Raises', 'Warns'):
+                self[section] = self._parse_param_list(content)
+            elif section.startswith('.. index::'):
+                self['index'] = self._parse_index(section, content)
+            elif section == 'See Also':
+                self['See Also'] = self._parse_see_also(content)
+            else:
+                self[section] = content
+
+    # string conversion routines
+
+    def _str_header(self, name, symbol='-'):
+        return [name, len(name)*symbol]
+
+    def _str_indent(self, doc, indent=4):
+        out = []
+        for line in doc:
+            out += [' '*indent + line]
+        return out
+
+    def _str_signature(self):
+        if self['Signature']:
+            return [self['Signature'].replace('*','\*')] + ['']
+        else:
+            return ['']
+
+    def _str_summary(self):
+        if self['Summary']:
+            return self['Summary'] + ['']
+        else:
+            return []
+
+    def _str_extended_summary(self):
+        if self['Extended Summary']:
+            return self['Extended Summary'] + ['']
+        else:
+            return []
+
+    def _str_param_list(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            for param,param_type,desc in self[name]:
+                out += ['%s : %s' % (param, param_type)]
+                out += self._str_indent(desc)
+            out += ['']
+        return out
+
+    def _str_section(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            out += self[name]
+            out += ['']
+        return out
+
+    def _str_see_also(self, func_role):
+        if not self['See Also']: return []
+        out = []
+        out += self._str_header("See Also")
+        last_had_desc = True
+        for func, desc, role in self['See Also']:
+            if role:
+                link = ':%s:`%s`' % (role, func)
+            elif func_role:
+                link = ':%s:`%s`' % (func_role, func)
+            else:
+                link = "`%s`_" % func
+            if desc or last_had_desc:
+                out += ['']
+                out += [link]
+            else:
+                out[-1] += ", %s" % link
+            if desc:
+                out += self._str_indent([' '.join(desc)])
+                last_had_desc = True
+            else:
+                last_had_desc = False
+        out += ['']
+        return out
+
+    def _str_index(self):
+        idx = self['index']
+        out = []
+        out += ['.. index:: %s' % idx.get('default','')]
+        for section, references in idx.items():
+            if section == 'default':
+                continue
+            out += ['   :%s: %s' % (section, ', '.join(references))]
+        return out
+
+    def __str__(self, func_role=''):
+        out = []
+        out += self._str_signature()
+        out += self._str_summary()
+        out += self._str_extended_summary()
+        for param_list in ('Parameters','Returns','Raises'):
+            out += self._str_param_list(param_list)
+        out += self._str_section('Warnings')
+        out += self._str_see_also(func_role)
+        for s in ('Notes','References','Examples'):
+            out += self._str_section(s)
+        out += self._str_index()
+        return '\n'.join(out)
+
+
+def indent(str,indent=4):
+    indent_str = ' '*indent
+    if str is None:
+        return indent_str
+    lines = str.split('\n')
+    return '\n'.join(indent_str + l for l in lines)
+
+def dedent_lines(lines):
+    """Deindent a list of lines maximally"""
+    return textwrap.dedent("\n".join(lines)).split("\n")
+
+def header(text, style='-'):
+    return text + '\n' + style*len(text) + '\n'
+
+
+class FunctionDoc(NumpyDocString):
+    def __init__(self, func, role='func', doc=None):
+        self._f = func
+        self._role = role # e.g. "func" or "meth"
+        if doc is None:
+            doc = inspect.getdoc(func) or ''
+        try:
+            NumpyDocString.__init__(self, doc)
+        except ValueError as e:
+            print('*'*78)
+            print("ERROR: '%s' while parsing `%s`" % (e, self._f))
+            print('*'*78)
+            #print "Docstring follows:"
+            #print doclines
+            #print '='*78
+
+        if not self['Signature']:
+            func, func_name = self.get_func()
+            try:
+                # try to read signature
+                argspec = inspect.getargspec(func)
+                argspec = inspect.formatargspec(*argspec)
+                argspec = argspec.replace('*','\*')
+                signature = '%s%s' % (func_name, argspec)
+            except TypeError as e:
+                signature = '%s()' % func_name
+            self['Signature'] = signature
+
+    def get_func(self):
+        func_name = getattr(self._f, '__name__', self.__class__.__name__)
+        if inspect.isclass(self._f):
+            func = getattr(self._f, '__call__', self._f.__init__)
+        else:
+            func = self._f
+        return func, func_name
+            
+    def __str__(self):
+        out = ''
+
+        func, func_name = self.get_func()
+        signature = self['Signature'].replace('*', '\*')
+
+        roles = {'func': 'function',
+                 'meth': 'method'}
+
+        if self._role:
+            if self._role not in roles:
+                print("Warning: invalid role %s" % self._role)
+            out += '.. %s:: %s\n    \n\n' % (roles.get(self._role,''),
+                                             func_name)
+
+        out += super(FunctionDoc, self).__str__(func_role=self._role)
+        return out
+
+
+class ClassDoc(NumpyDocString):
+    def __init__(self,cls,modulename='',func_doc=FunctionDoc,doc=None):
+        if not inspect.isclass(cls):
+            raise ValueError("Initialise using a class. Got %r" % cls)
+        self._cls = cls
+
+        if modulename and not modulename.endswith('.'):
+            modulename += '.'
+        self._mod = modulename
+        self._name = cls.__name__
+        self._func_doc = func_doc
+
+        if doc is None:
+            doc = pydoc.getdoc(cls)
+
+        NumpyDocString.__init__(self, doc)
+
+    @property
+    def methods(self):
+        return [name for name,func in inspect.getmembers(self._cls)
+                if not name.startswith('_') and callable(func)]
+
+    def __str__(self):
+        out = ''
+        out += super(ClassDoc, self).__str__()
+        out += "\n\n"
+
+        #for m in self.methods:
+        #    print "Parsing `%s`" % m
+        #    out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n'
+        #    out += '.. index::\n   single: %s; %s\n\n' % (self._name, m)
+
+        return out
+
+

doc/sphinxext/numpydoc/docscrape_sphinx.py

@@ -0,0 +1,136 @@
+import re, inspect, textwrap, pydoc
+from docscrape import NumpyDocString, FunctionDoc, ClassDoc
+
+class SphinxDocString(NumpyDocString):
+    # string conversion routines
+    def _str_header(self, name, symbol='`'):
+        return ['.. rubric:: ' + name, '']
+
+    def _str_field_list(self, name):
+        return [':' + name + ':']
+
+    def _str_indent(self, doc, indent=4):
+        out = []
+        for line in doc:
+            out += [' '*indent + line]
+        return out
+
+    def _str_signature(self):
+        return ['']
+        if self['Signature']:
+            return ['``%s``' % self['Signature']] + ['']
+        else:
+            return ['']
+
+    def _str_summary(self):
+        return self['Summary'] + ['']
+
+    def _str_extended_summary(self):
+        return self['Extended Summary'] + ['']
+
+    def _str_param_list(self, name):
+        out = []
+        if self[name]:
+            out += self._str_field_list(name)
+            out += ['']
+            for param,param_type,desc in self[name]:
+                out += self._str_indent(['**%s** : %s' % (param.strip(),
+                                                          param_type)])
+                out += ['']
+                out += self._str_indent(desc,8)
+                out += ['']
+        return out
+
+    def _str_section(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            out += ['']
+            content = textwrap.dedent("\n".join(self[name])).split("\n")
+            out += content
+            out += ['']
+        return out
+
+    def _str_see_also(self, func_role):
+        out = []
+        if self['See Also']:
+            see_also = super(SphinxDocString, self)._str_see_also(func_role)
+            out = ['.. seealso::', '']
+            out += self._str_indent(see_also[2:])
+        return out
+
+    def _str_warnings(self):
+        out = []
+        if self['Warnings']:
+            out = ['.. warning::', '']
+            out += self._str_indent(self['Warnings'])
+        return out
+
+    def _str_index(self):
+        idx = self['index']
+        out = []
+        if len(idx) == 0:
+            return out
+
+        out += ['.. index:: %s' % idx.get('default','')]
+        for section, references in idx.items():
+            if section == 'default':
+                continue
+            elif section == 'refguide':
+                out += ['   single: %s' % (', '.join(references))]
+            else:
+                out += ['   %s: %s' % (section, ','.join(references))]
+        return out
+
+    def _str_references(self):
+        out = []
+        if self['References']:
+            out += self._str_header('References')
+            if isinstance(self['References'], str):
+                self['References'] = [self['References']]
+            out.extend(self['References'])
+            out += ['']
+        return out
+
+    def __str__(self, indent=0, func_role="obj"):
+        out = []
+        out += self._str_signature()
+        out += self._str_index() + ['']
+        out += self._str_summary()
+        out += self._str_extended_summary()
+        for param_list in ('Parameters', 'Attributes', 'Methods',
+                           'Returns','Raises'):
+            out += self._str_param_list(param_list)
+        out += self._str_warnings()
+        out += self._str_see_also(func_role)
+        out += self._str_section('Notes')
+        out += self._str_references()
+        out += self._str_section('Examples')
+        out = self._str_indent(out,indent)
+        return '\n'.join(out)
+
+class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
+    pass
+
+class SphinxClassDoc(SphinxDocString, ClassDoc):
+    pass
+
+def get_doc_object(obj, what=None, doc=None):
+    if what is None:
+        if inspect.isclass(obj):
+            what = 'class'
+        elif inspect.ismodule(obj):
+            what = 'module'
+        elif callable(obj):
+            what = 'function'
+        else:
+            what = 'object'
+    if what == 'class':
+        return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc, doc=doc)
+    elif what in ('function', 'method'):
+        return SphinxFunctionDoc(obj, '', doc=doc)
+    else:
+        if doc is None:
+            doc = pydoc.getdoc(obj)
+        return SphinxDocString(doc)
+

doc/sphinxext/numpydoc/inheritance_diagram.py

@@ -0,0 +1,407 @@
+"""
+Defines a docutils directive for inserting inheritance diagrams.
+
+Provide the directive with one or more classes or modules (separated
+by whitespace).  For modules, all of the classes in that module will
+be used.
+
+Example::
+
+   Given the following classes:
+
+   class A: pass
+   class B(A): pass
+   class C(A): pass
+   class D(B, C): pass
+   class E(B): pass
+
+   .. inheritance-diagram: D E
+
+   Produces a graph like the following:
+
+               A
+              / \
+             B   C
+            / \ /
+           E   D
+
+The graph is inserted as a PNG+image map into HTML and a PDF in
+LaTeX.
+"""
+
+import inspect
+import os
+import re
+import subprocess
+try:
+    from hashlib import md5
+except ImportError:
+    from md5 import md5
+
+from docutils.nodes import Body, Element
+from docutils.parsers.rst import directives
+from sphinx.roles import xfileref_role
+
+def my_import(name):
+    """Module importer - taken from the python documentation.
+
+    This function allows importing names with dots in them."""
+    
+    mod = __import__(name)
+    components = name.split('.')
+    for comp in components[1:]:
+        mod = getattr(mod, comp)
+    return mod
+
+class DotException(Exception):
+    pass
+
+class InheritanceGraph:
+    """
+    Given a list of classes, determines the set of classes that
+    they inherit from all the way to the root "object", and then
+    is able to generate a graphviz dot graph from them.
+    """
+    def __init__(self, class_names, show_builtins=False):
+        """
+        *class_names* is a list of child classes to show bases from.
+
+        If *show_builtins* is True, then Python builtins will be shown
+        in the graph.
+        """
+        self.class_names = class_names
+        self.classes = self._import_classes(class_names)
+        self.all_classes = self._all_classes(self.classes)
+        if len(self.all_classes) == 0:
+            raise ValueError("No classes found for inheritance diagram")
+        self.show_builtins = show_builtins
+
+    py_sig_re = re.compile(r'''^([\w.]*\.)?    # class names
+                           (\w+)  \s* $        # optionally arguments
+                           ''', re.VERBOSE)
+
+    def _import_class_or_module(self, name):
+        """
+        Import a class using its fully-qualified *name*.
+        """
+        try:
+            path, base = self.py_sig_re.match(name).groups()
+        except:
+            raise ValueError(
+                "Invalid class or module '%s' specified for inheritance diagram" % name)
+        fullname = (path or '') + base
+        path = (path and path.rstrip('.'))
+        if not path:
+            path = base
+        try:
+            module = __import__(path, None, None, [])
+            # We must do an import of the fully qualified name.  Otherwise if a
+            # subpackage 'a.b' is requested where 'import a' does NOT provide
+            # 'a.b' automatically, then 'a.b' will not be found below.  This
+            # second call will force the equivalent of 'import a.b' to happen
+            # after the top-level import above.
+            my_import(fullname)
+            
+        except ImportError:
+            raise ValueError(
+                "Could not import class or module '%s' specified for inheritance diagram" % name)
+
+        try:
+            todoc = module
+            for comp in fullname.split('.')[1:]:
+                todoc = getattr(todoc, comp)
+        except AttributeError:
+            raise ValueError(
+                "Could not find class or module '%s' specified for inheritance diagram" % name)
+
+        # If a class, just return it
+        if inspect.isclass(todoc):
+            return [todoc]
+        elif inspect.ismodule(todoc):
+            classes = []
+            for cls in list(todoc.__dict__.values()):
+                if inspect.isclass(cls) and cls.__module__ == todoc.__name__:
+                    classes.append(cls)
+            return classes
+        raise ValueError(
+            "'%s' does not resolve to a class or module" % name)
+
+    def _import_classes(self, class_names):
+        """
+        Import a list of classes.
+        """
+        classes = []
+        for name in class_names:
+            classes.extend(self._import_class_or_module(name))
+        return classes
+
+    def _all_classes(self, classes):
+        """
+        Return a list of all classes that are ancestors of *classes*.
+        """
+        all_classes = {}
+
+        def recurse(cls):
+            all_classes[cls] = None
+            for c in cls.__bases__:
+                if c not in all_classes:
+                    recurse(c)
+
+        for cls in classes:
+            recurse(cls)
+
+        return list(all_classes.keys())
+
+    def class_name(self, cls, parts=0):
+        """
+        Given a class object, return a fully-qualified name.  This
+        works for things I've tested in matplotlib so far, but may not
+        be completely general.
+        """
+        module = cls.__module__
+        if module == '__builtin__':
+            fullname = cls.__name__
+        else:
+            fullname = "%s.%s" % (module, cls.__name__)
+        if parts == 0:
+            return fullname
+        name_parts = fullname.split('.')
+        return '.'.join(name_parts[-parts:])
+
+    def get_all_class_names(self):
+        """
+        Get all of the class names involved in the graph.
+        """
+        return [self.class_name(x) for x in self.all_classes]
+
+    # These are the default options for graphviz
+    default_graph_options = {
+        "rankdir": "LR",
+        "size": '"8.0, 12.0"'
+        }
+    default_node_options = {
+        "shape": "box",
+        "fontsize": 10,
+        "height": 0.25,
+        "fontname": "Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",
+        "style": '"setlinewidth(0.5)"'
+        }
+    default_edge_options = {
+        "arrowsize": 0.5,
+        "style": '"setlinewidth(0.5)"'
+        }
+
+    def _format_node_options(self, options):
+        return ','.join(["%s=%s" % x for x in list(options.items())])
+    def _format_graph_options(self, options):
+        return ''.join(["%s=%s;\n" % x for x in list(options.items())])
+
+    def generate_dot(self, fd, name, parts=0, urls={},
+                     graph_options={}, node_options={},
+                     edge_options={}):
+        """
+        Generate a graphviz dot graph from the classes that
+        were passed in to __init__.
+
+        *fd* is a Python file-like object to write to.
+
+        *name* is the name of the graph
+
+        *urls* is a dictionary mapping class names to http urls
+
+        *graph_options*, *node_options*, *edge_options* are
+        dictionaries containing key/value pairs to pass on as graphviz
+        properties.
+        """
+        g_options = self.default_graph_options.copy()
+        g_options.update(graph_options)
+        n_options = self.default_node_options.copy()
+        n_options.update(node_options)
+        e_options = self.default_edge_options.copy()
+        e_options.update(edge_options)
+
+        fd.write('digraph %s {\n' % name)
+        fd.write(self._format_graph_options(g_options))
+
+        for cls in self.all_classes:
+            if not self.show_builtins and cls in list(__builtins__.values()):
+                continue
+
+            name = self.class_name(cls, parts)
+
+            # Write the node
+            this_node_options = n_options.copy()
+            url = urls.get(self.class_name(cls))
+            if url is not None:
+                this_node_options['URL'] = '"%s"' % url
+            fd.write('  "%s" [%s];\n' %
+                     (name, self._format_node_options(this_node_options)))
+
+            # Write the edges
+            for base in cls.__bases__:
+                if not self.show_builtins and base in list(__builtins__.values()):
+                    continue
+
+                base_name = self.class_name(base, parts)
+                fd.write('  "%s" -> "%s" [%s];\n' %
+                         (base_name, name,
+                          self._format_node_options(e_options)))
+        fd.write('}\n')
+
+    def run_dot(self, args, name, parts=0, urls={},
+                graph_options={}, node_options={}, edge_options={}):
+        """
+        Run graphviz 'dot' over this graph, returning whatever 'dot'
+        writes to stdout.
+
+        *args* will be passed along as commandline arguments.
+
+        *name* is the name of the graph
+
+        *urls* is a dictionary mapping class names to http urls
+
+        Raises DotException for any of the many os and
+        installation-related errors that may occur.
+        """
+        try:
+            dot = subprocess.Popen(['dot'] + list(args),
+                                   stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                   close_fds=True)
+        except OSError:
+            raise DotException("Could not execute 'dot'.  Are you sure you have 'graphviz' installed?")
+        except ValueError:
+            raise DotException("'dot' called with invalid arguments")
+        except:
+            raise DotException("Unexpected error calling 'dot'")
+
+        self.generate_dot(dot.stdin, name, parts, urls, graph_options,
+                          node_options, edge_options)
+        dot.stdin.close()
+        result = dot.stdout.read()
+        returncode = dot.wait()
+        if returncode != 0:
+            raise DotException("'dot' returned the errorcode %d" % returncode)
+        return result
+
+class inheritance_diagram(Body, Element):
+    """
+    A docutils node to use as a placeholder for the inheritance
+    diagram.
+    """
+    pass
+
+def inheritance_diagram_directive(name, arguments, options, content, lineno,
+                                  content_offset, block_text, state,
+                                  state_machine):
+    """
+    Run when the inheritance_diagram directive is first encountered.
+    """
+    node = inheritance_diagram()
+
+    class_names = arguments
+
+    # Create a graph starting with the list of classes
+    graph = InheritanceGraph(class_names)
+
+    # Create xref nodes for each target of the graph's image map and
+    # add them to the doc tree so that Sphinx can resolve the
+    # references to real URLs later.  These nodes will eventually be
+    # removed from the doctree after we're done with them.
+    for name in graph.get_all_class_names():
+        refnodes, x = xfileref_role(
+            'class', ':class:`%s`' % name, name, 0, state)
+        node.extend(refnodes)
+    # Store the graph object so we can use it to generate the
+    # dot file later
+    node['graph'] = graph
+    # Store the original content for use as a hash
+    node['parts'] = options.get('parts', 0)
+    node['content'] = " ".join(class_names)
+    return [node]
+
+def get_graph_hash(node):
+    return md5(node['content'] + str(node['parts'])).hexdigest()[-10:]
+
+def html_output_graph(self, node):
+    """
+    Output the graph for HTML.  This will insert a PNG with clickable
+    image map.
+    """
+    graph = node['graph']
+    parts = node['parts']
+
+    graph_hash = get_graph_hash(node)
+    name = "inheritance%s" % graph_hash
+    path = '_images'
+    dest_path = os.path.join(setup.app.builder.outdir, path)
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    png_path = os.path.join(dest_path, name + ".png")
+    path = setup.app.builder.imgpath
+
+    # Create a mapping from fully-qualified class names to URLs.
+    urls = {}
+    for child in node:
+        if child.get('refuri') is not None:
+            urls[child['reftitle']] = child.get('refuri')
+        elif child.get('refid') is not None:
+            urls[child['reftitle']] = '#' + child.get('refid')
+
+    # These arguments to dot will save a PNG file to disk and write
+    # an HTML image map to stdout.
+    image_map = graph.run_dot(['-Tpng', '-o%s' % png_path, '-Tcmapx'],
+                              name, parts, urls)
+    return ('<img src="%s/%s.png" usemap="#%s" class="inheritance"/>%s' %
+            (path, name, name, image_map))
+
+def latex_output_graph(self, node):
+    """
+    Output the graph for LaTeX.  This will insert a PDF.
+    """
+    graph = node['graph']
+    parts = node['parts']
+
+    graph_hash = get_graph_hash(node)
+    name = "inheritance%s" % graph_hash
+    dest_path = os.path.abspath(os.path.join(setup.app.builder.outdir, '_images'))
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    pdf_path = os.path.abspath(os.path.join(dest_path, name + ".pdf"))
+
+    graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
+                  name, parts, graph_options={'size': '"6.0,6.0"'})
+    return '\n\\includegraphics{%s}\n\n' % pdf_path
+
+def visit_inheritance_diagram(inner_func):
+    """
+    This is just a wrapper around html/latex_output_graph to make it
+    easier to handle errors and insert warnings.
+    """
+    def visitor(self, node):
+        try:
+            content = inner_func(self, node)
+        except DotException as e:
+            # Insert the exception as a warning in the document
+            warning = self.document.reporter.warning(str(e), line=node.line)
+            warning.parent = node
+            node.children = [warning]
+        else:
+            source = self.document.attributes['source']
+            self.body.append(content)
+            node.children = []
+    return visitor
+
+def do_nothing(self, node):
+    pass
+
+def setup(app):
+    setup.app = app
+    setup.confdir = app.confdir
+
+    app.add_node(
+        inheritance_diagram,
+        latex=(visit_inheritance_diagram(latex_output_graph), do_nothing),
+        html=(visit_inheritance_diagram(html_output_graph), do_nothing))
+    app.add_directive(
+        'inheritance-diagram', inheritance_diagram_directive,
+        False, (1, 100, 0), parts = directives.nonnegative_int)

doc/sphinxext/numpydoc/ipython_console_highlighting.py

@@ -0,0 +1,114 @@
+"""reST directive for syntax-highlighting ipython interactive sessions.
+
+XXX - See what improvements can be made based on the new (as of Sept 2009)
+'pycon' lexer for the python console.  At the very least it will give better
+highlighted tracebacks.
+"""
+
+#-----------------------------------------------------------------------------
+# Needed modules
+
+# Standard library
+import re
+
+# Third party
+from pygments.lexer import Lexer, do_insertions
+from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer, 
+                                   PythonTracebackLexer)
+from pygments.token import Comment, Generic
+
+from sphinx import highlighting
+
+#-----------------------------------------------------------------------------
+# Global constants
+line_re = re.compile('.*?\n')
+
+#-----------------------------------------------------------------------------
+# Code begins - classes and functions
+
+class IPythonConsoleLexer(Lexer):
+    """
+    For IPython console output or doctests, such as:
+
+    .. sourcecode:: ipython
+
+      In [1]: a = 'foo'
+
+      In [2]: a
+      Out[2]: 'foo'
+
+      In [3]: print a
+      foo
+
+      In [4]: 1 / 0
+
+    Notes:
+
+      - Tracebacks are not currently supported.
+
+      - It assumes the default IPython prompts, not customized ones.
+    """
+    
+    name = 'IPython console session'
+    aliases = ['ipython']
+    mimetypes = ['text/x-ipython-console']
+    input_prompt = re.compile("(In \[[0-9]+\]: )|(   \.\.\.+:)")
+    output_prompt = re.compile("(Out\[[0-9]+\]: )|(   \.\.\.+:)")
+    continue_prompt = re.compile("   \.\.\.+:")
+    tb_start = re.compile("\-+")
+
+    def get_tokens_unprocessed(self, text):
+        pylexer = PythonLexer(**self.options)
+        tblexer = PythonTracebackLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        for match in line_re.finditer(text):
+            line = match.group()
+            input_prompt = self.input_prompt.match(line)
+            continue_prompt = self.continue_prompt.match(line.rstrip())
+            output_prompt = self.output_prompt.match(line)
+            if line.startswith("#"):
+                insertions.append((len(curcode),
+                                   [(0, Comment, line)]))
+            elif input_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, input_prompt.group())]))
+                curcode += line[input_prompt.end():]
+            elif continue_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, continue_prompt.group())]))
+                curcode += line[continue_prompt.end():]
+            elif output_prompt is not None:
+                # Use the 'error' token for output.  We should probably make
+                # our own token, but error is typicaly in a bright color like
+                # red, so it works fine for our output prompts.
+                insertions.append((len(curcode),
+                                   [(0, Generic.Error, output_prompt.group())]))
+                curcode += line[output_prompt.end():]
+            else:
+                if curcode:
+                    for item in do_insertions(insertions,
+                                              pylexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                        curcode = ''
+                        insertions = []
+                yield match.start(), Generic.Output, line
+        if curcode:
+            for item in do_insertions(insertions,
+                                      pylexer.get_tokens_unprocessed(curcode)):
+                yield item
+
+
+def setup(app):
+    """Setup as a sphinx extension."""
+
+    # This is only a lexer, so adding it below to pygments appears sufficient.
+    # But if somebody knows that the right API usage should be to do that via
+    # sphinx, by all means fix it here.  At least having this setup.py
+    # suppresses the sphinx warning we'd get without it.
+    pass
+
+#-----------------------------------------------------------------------------
+# Register the extension as a valid pygments lexer
+highlighting.lexers['ipython'] = IPythonConsoleLexer()

doc/sphinxext/numpydoc/numpydoc.py

@@ -0,0 +1,116 @@
+"""
+========
+numpydoc
+========
+
+Sphinx extension that handles docstrings in the Numpy standard format. [1]
+
+It will:
+
+- Convert Parameters etc. sections to field lists.
+- Convert See Also section to a See also entry.
+- Renumber references.
+- Extract the signature from the docstring, if it can't be determined otherwise.
+
+.. [1] http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard
+
+"""
+
+import os, re, pydoc
+from docscrape_sphinx import get_doc_object, SphinxDocString
+import inspect
+
+def mangle_docstrings(app, what, name, obj, options, lines,
+                      reference_offset=[0]):
+    if what == 'module':
+        # Strip top title
+        title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
+                              re.I|re.S)
+        lines[:] = title_re.sub('', "\n".join(lines)).split("\n")
+    else:
+        doc = get_doc_object(obj, what, "\n".join(lines))
+        lines[:] = str(doc).split("\n")
+
+    if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
+           obj.__name__:
+        if hasattr(obj, '__module__'):
+            v = dict(full_name="%s.%s" % (obj.__module__, obj.__name__))
+        else:
+            v = dict(full_name=obj.__name__)
+        lines += ['', '.. htmlonly::', '']
+        lines += ['    %s' % x for x in
+                  (app.config.numpydoc_edit_link % v).split("\n")]
+
+    # replace reference numbers so that there are no duplicates
+    references = []
+    for l in lines:
+        l = l.strip()
+        if l.startswith('.. ['):
+            try:
+                references.append(int(l[len('.. ['):l.index(']')]))
+            except ValueError:
+                print("WARNING: invalid reference in %s docstring" % name)
+
+    # Start renaming from the biggest number, otherwise we may
+    # overwrite references.
+    references.sort()
+    if references:
+        for i, line in enumerate(lines):
+            for r in references:
+                new_r = reference_offset[0] + r
+                lines[i] = lines[i].replace('[%d]_' % r,
+                                            '[%d]_' % new_r)
+                lines[i] = lines[i].replace('.. [%d]' % r,
+                                            '.. [%d]' % new_r)
+
+    reference_offset[0] += len(references)
+
+def mangle_signature(app, what, name, obj, options, sig, retann):
+    # Do not try to inspect classes that don't define `__init__`
+    if (inspect.isclass(obj) and
+        'initializes x; see ' in pydoc.getdoc(obj.__init__)):
+        return '', ''
+
+    if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
+    if not hasattr(obj, '__doc__'): return
+
+    doc = SphinxDocString(pydoc.getdoc(obj))
+    if doc['Signature']:
+        sig = re.sub("^[^(]*", "", doc['Signature'])
+        return sig, ''
+
+def initialize(app):
+    try:
+        app.connect('autodoc-process-signature', mangle_signature)
+    except:
+        monkeypatch_sphinx_ext_autodoc()
+
+def setup(app, get_doc_object_=get_doc_object):
+    global get_doc_object
+    get_doc_object = get_doc_object_
+    
+    app.connect('autodoc-process-docstring', mangle_docstrings)
+    app.connect('builder-inited', initialize)
+    app.add_config_value('numpydoc_edit_link', None, True)
+
+#------------------------------------------------------------------------------
+# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
+#------------------------------------------------------------------------------
+
+def monkeypatch_sphinx_ext_autodoc():
+    global _original_format_signature
+    import sphinx.ext.autodoc
+
+    if sphinx.ext.autodoc.format_signature is our_format_signature:
+        return
+
+    print("[numpydoc] Monkeypatching sphinx.ext.autodoc ...")
+    _original_format_signature = sphinx.ext.autodoc.format_signature
+    sphinx.ext.autodoc.format_signature = our_format_signature
+
+def our_format_signature(what, obj):
+    r = mangle_signature(None, what, None, obj, None, None, None)
+    if r is not None:
+        return r[0]
+    else:
+        return _original_format_signature(what, obj)

doc/sphinxext/numpydoc/plot_directive.py

@@ -0,0 +1,773 @@
+"""
+A directive for including a matplotlib plot in a Sphinx document.
+
+By default, in HTML output, `plot` will include a .png file with a
+link to a high-res .png and .pdf.  In LaTeX output, it will include a
+.pdf.
+
+The source code for the plot may be included in one of three ways:
+
+  1. **A path to a source file** as the argument to the directive::
+
+       .. plot:: path/to/plot.py
+
+     When a path to a source file is given, the content of the
+     directive may optionally contain a caption for the plot::
+
+       .. plot:: path/to/plot.py
+
+          This is the caption for the plot
+
+     Additionally, one my specify the name of a function to call (with
+     no arguments) immediately after importing the module::
+
+       .. plot:: path/to/plot.py plot_function1
+
+  2. Included as **inline content** to the directive::
+
+       .. plot::
+
+          import matplotlib.pyplot as plt
+          import matplotlib.image as mpimg
+          import numpy as np
+          img = mpimg.imread('_static/stinkbug.png')
+          imgplot = plt.imshow(img)
+
+  3. Using **doctest** syntax::
+
+       .. plot::
+          A plotting example:
+          >>> import matplotlib.pyplot as plt
+          >>> plt.plot([1,2,3], [4,5,6])
+
+Options
+-------
+
+The ``plot`` directive supports the following options:
+
+    format : {'python', 'doctest'}
+        Specify the format of the input
+
+    include-source : bool
+        Whether to display the source code. The default can be changed
+        using the `plot_include_source` variable in conf.py
+
+    encoding : str
+        If this source file is in a non-UTF8 or non-ASCII encoding,
+        the encoding must be specified using the `:encoding:` option.
+        The encoding will not be inferred using the ``-*- coding -*-``
+        metacomment.
+
+    context : bool
+        If provided, the code will be run in the context of all
+        previous plot directives for which the `:context:` option was
+        specified.  This only applies to inline code plot directives,
+        not those run from files.
+
+    nofigs : bool
+        If specified, the code block will be run, but no figures will
+        be inserted.  This is usually useful with the ``:context:``
+        option.
+
+Additionally, this directive supports all of the options of the
+`image` directive, except for `target` (since plot will add its own
+target).  These include `alt`, `height`, `width`, `scale`, `align` and
+`class`.
+
+Configuration options
+---------------------
+
+The plot directive has the following configuration options:
+
+    plot_include_source
+        Default value for the include-source option
+
+    plot_pre_code
+        Code that should be executed before each plot.
+
+    plot_basedir
+        Base directory, to which ``plot::`` file names are relative
+        to.  (If None or empty, file names are relative to the
+        directoly where the file containing the directive is.)
+
+    plot_formats
+        File formats to generate. List of tuples or strings::
+
+            [(suffix, dpi), suffix, ...]
+
+        that determine the file format and the DPI. For entries whose
+        DPI was omitted, sensible defaults are chosen.
+
+    plot_html_show_formats
+        Whether to show links to the files in HTML.
+
+    plot_rcparams
+        A dictionary containing any non-standard rcParams that should
+        be applied before each plot.
+
+"""
+
+import sys, os, glob, shutil, imp, warnings, io, re, textwrap, \
+       traceback, exceptions
+
+from docutils.parsers.rst import directives
+from docutils import nodes
+from docutils.parsers.rst.directives.images import Image
+align = Image.align
+import sphinx
+
+sphinx_version = sphinx.__version__.split(".")
+# The split is necessary for sphinx beta versions where the string is
+# '6b1'
+sphinx_version = tuple([int(re.split('[a-z]', x)[0])
+                        for x in sphinx_version[:2]])
+
+try:
+    # Sphinx depends on either Jinja or Jinja2
+    import jinja2
+    def format_template(template, **kw):
+        return jinja2.Template(template).render(**kw)
+except ImportError:
+    import jinja
+    def format_template(template, **kw):
+        return jinja.from_string(template, **kw)
+
+import matplotlib
+import matplotlib.cbook as cbook
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from matplotlib import _pylab_helpers
+
+__version__ = 2
+
+#------------------------------------------------------------------------------
+# Relative pathnames
+#------------------------------------------------------------------------------
+
+# os.path.relpath is new in Python 2.6
+try:
+    from os.path import relpath
+except ImportError:
+    # Copied from Python 2.7
+    if 'posix' in sys.builtin_module_names:
+        def relpath(path, start=os.path.curdir):
+            """Return a relative version of a path"""
+            from os.path import sep, curdir, join, abspath, commonprefix, \
+                 pardir
+
+            if not path:
+                raise ValueError("no path specified")
+
+            start_list = abspath(start).split(sep)
+            path_list = abspath(path).split(sep)
+
+            # Work out how much of the filepath is shared by start and path.
+            i = len(commonprefix([start_list, path_list]))
+
+            rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
+            if not rel_list:
+                return curdir
+            return join(*rel_list)
+    elif 'nt' in sys.builtin_module_names:
+        def relpath(path, start=os.path.curdir):
+            """Return a relative version of a path"""
+            from os.path import sep, curdir, join, abspath, commonprefix, \
+                 pardir, splitunc
+
+            if not path:
+                raise ValueError("no path specified")
+            start_list = abspath(start).split(sep)
+            path_list = abspath(path).split(sep)
+            if start_list[0].lower() != path_list[0].lower():
+                unc_path, rest = splitunc(path)
+                unc_start, rest = splitunc(start)
+                if bool(unc_path) ^ bool(unc_start):
+                    raise ValueError("Cannot mix UNC and non-UNC paths (%s and %s)"
+                                                                        % (path, start))
+                else:
+                    raise ValueError("path is on drive %s, start on drive %s"
+                                                        % (path_list[0], start_list[0]))
+            # Work out how much of the filepath is shared by start and path.
+            for i in range(min(len(start_list), len(path_list))):
+                if start_list[i].lower() != path_list[i].lower():
+                    break
+            else:
+                i += 1
+
+            rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
+            if not rel_list:
+                return curdir
+            return join(*rel_list)
+    else:
+        raise RuntimeError("Unsupported platform (no relpath available!)")
+
+#------------------------------------------------------------------------------
+# Registration hook
+#------------------------------------------------------------------------------
+
+def plot_directive(name, arguments, options, content, lineno,
+                   content_offset, block_text, state, state_machine):
+    return run(arguments, content, options, state_machine, state, lineno)
+plot_directive.__doc__ = __doc__
+
+def _option_boolean(arg):
+    if not arg or not arg.strip():
+        # no argument given, assume used as a flag
+        return True
+    elif arg.strip().lower() in ('no', '0', 'false'):
+        return False
+    elif arg.strip().lower() in ('yes', '1', 'true'):
+        return True
+    else:
+        raise ValueError('"%s" unknown boolean' % arg)
+
+def _option_format(arg):
+    return directives.choice(arg, ('python', 'doctest'))
+
+def _option_align(arg):
+    return directives.choice(arg, ("top", "middle", "bottom", "left", "center",
+                                   "right"))
+
+def mark_plot_labels(app, document):
+    """
+    To make plots referenceable, we need to move the reference from
+    the "htmlonly" (or "latexonly") node to the actual figure node
+    itself.
+    """
+    for name, explicit in document.nametypes.items():
+        if not explicit:
+            continue
+        labelid = document.nameids[name]
+        if labelid is None:
+            continue
+        node = document.ids[labelid]
+        if node.tagname in ('html_only', 'latex_only'):
+            for n in node:
+                if n.tagname == 'figure':
+                    sectname = name
+                    for c in n:
+                        if c.tagname == 'caption':
+                            sectname = c.astext()
+                            break
+
+                    node['ids'].remove(labelid)
+                    node['names'].remove(name)
+                    n['ids'].append(labelid)
+                    n['names'].append(name)
+                    document.settings.env.labels[name] = \
+                        document.settings.env.docname, labelid, sectname
+                    break
+
+def setup(app):
+    setup.app = app
+    setup.config = app.config
+    setup.confdir = app.confdir
+
+    options = {'alt': directives.unchanged,
+               'height': directives.length_or_unitless,
+               'width': directives.length_or_percentage_or_unitless,
+               'scale': directives.nonnegative_int,
+               'align': _option_align,
+               'class': directives.class_option,
+               'include-source': _option_boolean,
+               'format': _option_format,
+               'context': directives.flag,
+               'nofigs': directives.flag,
+               'encoding': directives.encoding
+               }
+
+    app.add_directive('plot', plot_directive, True, (0, 2, False), **options)
+    app.add_config_value('plot_pre_code', None, True)
+    app.add_config_value('plot_include_source', False, True)
+    app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True)
+    app.add_config_value('plot_basedir', None, True)
+    app.add_config_value('plot_html_show_formats', True, True)
+    app.add_config_value('plot_rcparams', {}, True)
+
+    app.connect('doctree-read', mark_plot_labels)
+
+#------------------------------------------------------------------------------
+# Doctest handling
+#------------------------------------------------------------------------------
+
+def contains_doctest(text):
+    try:
+        # check if it's valid Python as-is
+        compile(text, '<string>', 'exec')
+        return False
+    except SyntaxError:
+        pass
+    r = re.compile(r'^\s*>>>', re.M)
+    m = r.search(text)
+    return bool(m)
+
+def unescape_doctest(text):
+    """
+    Extract code from a piece of text, which contains either Python code
+    or doctests.
+
+    """
+    if not contains_doctest(text):
+        return text
+
+    code = ""
+    for line in text.split("\n"):
+        m = re.match(r'^\s*(>>>|\.\.\.) (.*)$', line)
+        if m:
+            code += m.group(2) + "\n"
+        elif line.strip():
+            code += "# " + line.strip() + "\n"
+        else:
+            code += "\n"
+    return code
+
+def split_code_at_show(text):
+    """
+    Split code at plt.show()
+
+    """
+
+    parts = []
+    is_doctest = contains_doctest(text)
+
+    part = []
+    for line in text.split("\n"):
+        if (not is_doctest and line.strip() == 'plt.show()') or \
+               (is_doctest and line.strip() == '>>> plt.show()'):
+            part.append(line)
+            parts.append("\n".join(part))
+            part = []
+        else:
+            part.append(line)
+    if "\n".join(part).strip():
+        parts.append("\n".join(part))
+    return parts
+
+#------------------------------------------------------------------------------
+# Template
+#------------------------------------------------------------------------------
+
+
+TEMPLATE = """
+{{ source_code }}
+
+{{ only_html }}
+
+   {% if source_link or (html_show_formats and not multi_image) %}
+   (
+   {%- if source_link -%}
+   `Source code <{{ source_link }}>`__
+   {%- endif -%}
+   {%- if html_show_formats and not multi_image -%}
+     {%- for img in images -%}
+       {%- for fmt in img.formats -%}
+         {%- if source_link or not loop.first -%}, {% endif -%}
+         `{{ fmt }} <{{ dest_dir }}/{{ img.basename }}.{{ fmt }}>`__
+       {%- endfor -%}
+     {%- endfor -%}
+   {%- endif -%}
+   )
+   {% endif %}
+
+   {% for img in images %}
+   .. figure:: {{ build_dir }}/{{ img.basename }}.png
+      {%- for option in options %}
+      {{ option }}
+      {% endfor %}
+
+      {% if html_show_formats and multi_image -%}
+        (
+        {%- for fmt in img.formats -%}
+        {%- if not loop.first -%}, {% endif -%}
+        `{{ fmt }} <{{ dest_dir }}/{{ img.basename }}.{{ fmt }}>`__
+        {%- endfor -%}
+        )
+      {%- endif -%}
+
+      {{ caption }}
+   {% endfor %}
+
+{{ only_latex }}
+
+   {% for img in images %}
+   .. image:: {{ build_dir }}/{{ img.basename }}.pdf
+   {% endfor %}
+
+"""
+
+exception_template = """
+.. htmlonly::
+
+   [`source code <%(linkdir)s/%(basename)s.py>`__]
+
+Exception occurred rendering plot.
+
+"""
+
+# the context of the plot for all directives specified with the
+# :context: option
+plot_context = dict()
+
+class ImageFile:
+    def __init__(self, basename, dirname):
+        self.basename = basename
+        self.dirname = dirname
+        self.formats = []
+
+    def filename(self, format):
+        return os.path.join(self.dirname, "%s.%s" % (self.basename, format))
+
+    def filenames(self):
+        return [self.filename(fmt) for fmt in self.formats]
+
+def out_of_date(original, derived):
+    """
+    Returns True if derivative is out-of-date wrt original,
+    both of which are full file paths.
+    """
+    return (not os.path.exists(derived) or
+            (os.path.exists(original) and
+             os.stat(derived).st_mtime < os.stat(original).st_mtime))
+
+class PlotError(RuntimeError):
+    pass
+
+def run_code(code, code_path, ns=None, function_name=None):
+    """
+    Import a Python module from a path, and run the function given by
+    name, if function_name is not None.
+    """
+
+    # Change the working directory to the directory of the example, so
+    # it can get at its data files, if any.  Add its path to sys.path
+    # so it can import any helper modules sitting beside it.
+
+    pwd = os.getcwd()
+    old_sys_path = list(sys.path)
+    if code_path is not None:
+        dirname = os.path.abspath(os.path.dirname(code_path))
+        os.chdir(dirname)
+        sys.path.insert(0, dirname)
+
+    # Redirect stdout
+    stdout = sys.stdout
+    sys.stdout = io.StringIO()
+
+    # Reset sys.argv
+    old_sys_argv = sys.argv
+    sys.argv = [code_path]
+
+    try:
+        try:
+            code = unescape_doctest(code)
+            if ns is None:
+                ns = {}
+            if not ns:
+                if setup.config.plot_pre_code is None:
+                    exec("import numpy as np\nfrom matplotlib import pyplot as plt\n", ns)
+                else:
+                    exec(setup.config.plot_pre_code, ns)
+            if "__main__" in code:
+                exec("__name__ = '__main__'", ns)
+            exec(code, ns)
+            if function_name is not None:
+                exec(function_name + "()", ns)
+        except (Exception, SystemExit) as err:
+            raise PlotError(traceback.format_exc())
+    finally:
+        os.chdir(pwd)
+        sys.argv = old_sys_argv
+        sys.path[:] = old_sys_path
+        sys.stdout = stdout
+    return ns
+
+def clear_state(plot_rcparams):
+    plt.close('all')
+    matplotlib.rc_file_defaults()
+    matplotlib.rcParams.update(plot_rcparams)
+
+def render_figures(code, code_path, output_dir, output_base, context,
+                   function_name, config):
+    """
+    Run a pyplot script and save the low and high res PNGs and a PDF
+    in outdir.
+
+    Save the images under *output_dir* with file names derived from
+    *output_base*
+    """
+    # -- Parse format list
+    default_dpi = {'png': 80, 'hires.png': 200, 'pdf': 200}
+    formats = []
+    plot_formats = config.plot_formats
+    if isinstance(plot_formats, str):
+        plot_formats = eval(plot_formats)
+    for fmt in plot_formats:
+        if isinstance(fmt, str):
+            formats.append((fmt, default_dpi.get(fmt, 80)))
+        elif type(fmt) in (tuple, list) and len(fmt)==2:
+            formats.append((str(fmt[0]), int(fmt[1])))
+        else:
+            raise PlotError('invalid image format "%r" in plot_formats' % fmt)
+
+    # -- Try to determine if all images already exist
+
+    code_pieces = split_code_at_show(code)
+
+    # Look for single-figure output files first
+    # Look for single-figure output files first
+    all_exists = True
+    img = ImageFile(output_base, output_dir)
+    for format, dpi in formats:
+        if out_of_date(code_path, img.filename(format)):
+            all_exists = False
+            break
+        img.formats.append(format)
+
+    if all_exists:
+        return [(code, [img])]
+
+    # Then look for multi-figure output files
+    results = []
+    all_exists = True
+    for i, code_piece in enumerate(code_pieces):
+        images = []
+        for j in range(1000):
+            if len(code_pieces) > 1:
+                img = ImageFile('%s_%02d_%02d' % (output_base, i, j), output_dir)
+            else:
+                img = ImageFile('%s_%02d' % (output_base, j), output_dir)
+            for format, dpi in formats:
+                if out_of_date(code_path, img.filename(format)):
+                    all_exists = False
+                    break
+                img.formats.append(format)
+
+            # assume that if we have one, we have them all
+            if not all_exists:
+                all_exists = (j > 0)
+                break
+            images.append(img)
+        if not all_exists:
+            break
+        results.append((code_piece, images))
+
+    if all_exists:
+        return results
+
+    # We didn't find the files, so build them
+
+    results = []
+    if context:
+        ns = plot_context
+    else:
+        ns = {}
+
+    for i, code_piece in enumerate(code_pieces):
+        if not context:
+            clear_state(config.plot_rcparams)
+        run_code(code_piece, code_path, ns, function_name)
+
+        images = []
+        fig_managers = _pylab_helpers.Gcf.get_all_fig_managers()
+        for j, figman in enumerate(fig_managers):
+            if len(fig_managers) == 1 and len(code_pieces) == 1:
+                img = ImageFile(output_base, output_dir)
+            elif len(code_pieces) == 1:
+                img = ImageFile("%s_%02d" % (output_base, j), output_dir)
+            else:
+                img = ImageFile("%s_%02d_%02d" % (output_base, i, j),
+                                output_dir)
+            images.append(img)
+            for format, dpi in formats:
+                try:
+                    figman.canvas.figure.savefig(img.filename(format), dpi=dpi)
+                except Exception as err:
+                    raise PlotError(traceback.format_exc())
+                img.formats.append(format)
+
+        results.append((code_piece, images))
+
+    if not context:
+        clear_state(config.plot_rcparams)
+
+    return results
+
+def run(arguments, content, options, state_machine, state, lineno):
+    # The user may provide a filename *or* Python code content, but not both
+    if arguments and content:
+        raise RuntimeError("plot:: directive can't have both args and content")
+
+    document = state_machine.document
+    config = document.settings.env.config
+    nofigs = 'nofigs' in options
+
+    options.setdefault('include-source', config.plot_include_source)
+    context = 'context' in options
+
+    rst_file = document.attributes['source']
+    rst_dir = os.path.dirname(rst_file)
+
+    if len(arguments):
+        if not config.plot_basedir:
+            source_file_name = os.path.join(setup.app.builder.srcdir,
+                                            directives.uri(arguments[0]))
+        else:
+            source_file_name = os.path.join(setup.app.builder.srcdir, config.plot_basedir,
+                                            directives.uri(arguments[0]))
+
+        # If there is content, it will be passed as a caption.
+        caption = '\n'.join(content)
+
+        # If the optional function name is provided, use it
+        if len(arguments) == 2:
+            function_name = arguments[1]
+        else:
+            function_name = None
+
+        fd = open(source_file_name, 'r')
+        code = fd.read()
+        fd.close()
+        output_base = os.path.basename(source_file_name)
+    else:
+        source_file_name = rst_file
+        code = textwrap.dedent("\n".join(map(str, content)))
+        counter = document.attributes.get('_plot_counter', 0) + 1
+        document.attributes['_plot_counter'] = counter
+        base, ext = os.path.splitext(os.path.basename(source_file_name))
+        output_base = '%s-%d.py' % (base, counter)
+        function_name = None
+        caption = ''
+
+    base, source_ext = os.path.splitext(output_base)
+    if source_ext in ('.py', '.rst', '.txt'):
+        output_base = base
+    else:
+        source_ext = ''
+
+    # ensure that LaTeX includegraphics doesn't choke in foo.bar.pdf filenames
+    output_base = output_base.replace('.', '-')
+
+    # is it in doctest format?
+    is_doctest = contains_doctest(code)
+    if 'format' in options:
+        if options['format'] == 'python':
+            is_doctest = False
+        else:
+            is_doctest = True
+
+    # determine output directory name fragment
+    source_rel_name = relpath(source_file_name, setup.app.srcdir)
+    source_rel_dir = os.path.dirname(source_rel_name)
+    while source_rel_dir.startswith(os.path.sep):
+        source_rel_dir = source_rel_dir[1:]
+
+    # build_dir: where to place output files (temporarily)
+    build_dir = os.path.join(os.path.dirname(setup.app.doctreedir),
+                             'plot_directive',
+                             source_rel_dir)
+    # get rid of .. in paths, also changes pathsep
+    # see note in Python docs for warning about symbolic links on Windows.
+    # need to compare source and dest paths at end
+    build_dir = os.path.normpath(build_dir)
+
+    if not os.path.exists(build_dir):
+        os.makedirs(build_dir)
+
+    # output_dir: final location in the builder's directory
+    dest_dir = os.path.abspath(os.path.join(setup.app.builder.outdir,
+                                            source_rel_dir))
+    if not os.path.exists(dest_dir):
+        os.makedirs(dest_dir) # no problem here for me, but just use built-ins
+
+    # how to link to files from the RST file
+    dest_dir_link = os.path.join(relpath(setup.app.srcdir, rst_dir),
+                                 source_rel_dir).replace(os.path.sep, '/')
+    build_dir_link = relpath(build_dir, rst_dir).replace(os.path.sep, '/')
+    source_link = dest_dir_link + '/' + output_base + source_ext
+
+    # make figures
+    try:
+        results = render_figures(code, source_file_name, build_dir, output_base,
+                                 context, function_name, config)
+        errors = []
+    except PlotError as err:
+        reporter = state.memo.reporter
+        sm = reporter.system_message(
+            2, "Exception occurred in plotting %s\n from %s:\n%s" % (output_base,
+                                                source_file_name, err),
+            line=lineno)
+        results = [(code, [])]
+        errors = [sm]
+
+    # Properly indent the caption
+    caption = '\n'.join('      ' + line.strip()
+                        for line in caption.split('\n'))
+
+    # generate output restructuredtext
+    total_lines = []
+    for j, (code_piece, images) in enumerate(results):
+        if options['include-source']:
+            if is_doctest:
+                lines = ['']
+                lines += [row.rstrip() for row in code_piece.split('\n')]
+            else:
+                lines = ['.. code-block:: python', '']
+                lines += ['    %s' % row.rstrip()
+                          for row in code_piece.split('\n')]
+            source_code = "\n".join(lines)
+        else:
+            source_code = ""
+
+        if nofigs:
+            images = []
+
+        opts = [':%s: %s' % (key, val) for key, val in list(options.items())
+                if key in ('alt', 'height', 'width', 'scale', 'align', 'class')]
+
+        only_html = ".. only:: html"
+        only_latex = ".. only:: latex"
+
+        if j == 0:
+            src_link = source_link
+        else:
+            src_link = None
+
+        result = format_template(
+            TEMPLATE,
+            dest_dir=dest_dir_link,
+            build_dir=build_dir_link,
+            source_link=src_link,
+            multi_image=len(images) > 1,
+            only_html=only_html,
+            only_latex=only_latex,
+            options=opts,
+            images=images,
+            source_code=source_code,
+            html_show_formats=config.plot_html_show_formats,
+            caption=caption)
+
+        total_lines.extend(result.split("\n"))
+        total_lines.extend("\n")
+
+    if total_lines:
+        state_machine.insert_input(total_lines, source=source_file_name)
+
+    # copy image files to builder's output directory, if necessary
+    if not os.path.exists(dest_dir):
+        cbook.mkdirs(dest_dir)
+
+    for code_piece, images in results:
+        for img in images:
+            for fn in img.filenames():
+                destimg = os.path.join(dest_dir, os.path.basename(fn))
+                if fn != destimg:
+                    shutil.copyfile(fn, destimg)
+
+    # copy script (if necessary)
+    #if source_file_name == rst_file:
+    target_name = os.path.join(dest_dir, output_base + source_ext)
+    f = open(target_name, 'w')
+    f.write(unescape_doctest(code))
+    f.close()
+
+    return errors

doc/sphinxext/sphinx_autorun/__init__.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+"""
+sphinxcontirb.autorun
+~~~~~~~~~~~~~~~~~~~~~~
+
+Run the code and insert stdout after the code block.
+"""
+import os
+from subprocess import PIPE, Popen
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.errors import SphinxError
+
+from sphinx_autorun import version
+
+__version__ = version.version
+
+
+class RunBlockError(SphinxError):
+    category = 'runblock error'
+
+
+class AutoRun(object):
+    here = os.path.abspath(__file__)
+    pycon = os.path.join(os.path.dirname(here), 'pycon.py')
+    config = {
+        'pycon': 'python ' + pycon,
+        'pycon_prefix_chars': 4,
+        'pycon_show_source': False,
+        'console': 'bash',
+        'console_prefix_chars': 1,
+    }
+
+    @classmethod
+    def builder_init(cls, app):
+        cls.config.update(app.builder.config.autorun_languages)
+
+
+class RunBlock(Directive):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'linenos': directives.flag,
+    }
+
+    def run(self):
+        config = AutoRun.config
+        language = self.arguments[0]
+
+        if language not in config:
+            raise RunBlockError('Unknown language %s' % language)
+
+        # Get configuration values for the language
+        args = config[language].split()
+        input_encoding = config.get(language+'_input_encoding', 'utf8')
+        output_encoding = config.get(language+'_output_encoding', 'utf8')
+        prefix_chars = config.get(language+'_prefix_chars', 0)
+        show_source = config.get(language+'_show_source', True)
+
+        # Build the code text
+        proc = Popen(args, bufsize=1, stdin=PIPE, stdout=PIPE, stderr=PIPE)
+        codelines = (line[prefix_chars:] for line in self.content)
+        code = u'\n'.join(codelines).encode(input_encoding)
+
+        # Run the code
+        stdout, stderr = proc.communicate(code)
+
+        # Process output
+        if stdout:
+            out = stdout.decode(output_encoding)
+        if stderr:
+            out = stderr.decode(output_encoding)
+
+        # Get the original code with prefixes
+        if show_source:
+            code = u'\n'.join(self.content)
+            code_out = u'\n'.join((code, out))
+        else:
+            code_out = out
+
+        literal = nodes.literal_block(code_out, code_out)
+        literal['language'] = language
+        literal['linenos'] = 'linenos' in self.options
+        return [literal]
+
+
+def setup(app):
+    app.add_directive('runblock', RunBlock)
+    app.connect('builder-inited', AutoRun.builder_init)
+    app.add_config_value('autorun_languages', AutoRun.config, 'env')

doc/sphinxext/sphinx_autorun/pycon.py

@@ -0,0 +1,31 @@
+import sys
+from code import InteractiveInterpreter
+
+
+def main():
+    """
+    Print lines of input along with output.
+    """
+    source_lines = (line.rstrip() for line in sys.stdin)
+    console = InteractiveInterpreter()
+    source = ''
+    try:
+        while True:
+            source = next(source_lines)
+            # Allow the user to ignore specific lines of output.
+            if not source.endswith('# ignore'):
+                print('>>>', source)
+            more = console.runsource(source)
+            while more:
+                next_line = next(source_lines)
+                print('...', next_line)
+                source += '\n' + next_line
+                more = console.runsource(source)
+    except StopIteration:
+        if more:
+            print('... ')
+            more = console.runsource(source + '\n')
+
+
+if __name__ == '__main__':
+    main()

doc/sphinxext/sphinx_autorun/version.py

@@ -0,0 +1,4 @@
+# coding: utf-8
+# file generated by setuptools_scm
+# don't change, don't track in version control
+version = '1.1.1'

doc/sphinxext/triqs_example/triqs_example.py

@@ -0,0 +1,123 @@
+import tempfile
+# -*- coding: utf-8 -*-
+# seems to be executed at the level of the conf.py
+# so we need to link the lib at that place...
+"""
+"""
+import os
+import codecs
+from os import path
+from subprocess import Popen,PIPE
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import directives
+from sphinx.errors import SphinxError
+
+class TriqsExampleError(SphinxError):
+    category = 'triqs_example error'
+
+class TriqsExampleRun:
+    #here = os.path.abspath(__file__)
+    #pycon = os.path.join(os.path.dirname(here),'pycon.py')
+    config = dict(
+    )
+    @classmethod
+    def builder_init(cls,app):
+        #cls.config.update(app.builder.config.autorun_languages)
+        #cls.config.update(app.builder.config.autocompile_opts)
+        pass 
+
+class TriqsExample(Directive):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'linenos': directives.flag,
+    }
+
+    def run(self):
+        document = self.state.document
+        filename = self.arguments[0]
+        if not document.settings.file_insertion_enabled:
+            return [document.reporter.warning('File insertion disabled',
+                                              line=self.lineno)]
+        env = document.settings.env
+        if filename.startswith('/') or filename.startswith(os.sep):
+            rel_fn = filename[1:]
+        else:
+            docdir = path.dirname(env.doc2path(env.docname, base=None))
+            rel_fn = path.normpath(path.join(docdir, filename))
+        try:
+            fn = path.join(env.srcdir, rel_fn)
+        except UnicodeDecodeError:
+            # the source directory is a bytestring with non-ASCII characters;
+            # let's try to encode the rel_fn in the file system encoding
+            rel_fn = rel_fn.encode(sys.getfilesystemencoding())
+            fn = path.join(env.srcdir, rel_fn)
+
+        encoding = self.options.get('encoding', env.config.source_encoding)
+        try:
+            f = codecs.open(fn, 'rU', encoding)
+            lines = f.readlines()
+            f.close()
+        except (IOError, OSError):
+            return [document.reporter.warning(
+                'Include file %r not found or reading it failed' % filename,
+                line=self.lineno)]
+        except UnicodeError:
+            return [document.reporter.warning(
+                'Encoding %r used for reading included file %r seems to '
+                'be wrong, try giving an :encoding: option' %
+                (encoding, filename))]
+
+        config = TriqsExampleRun.config
+
+        # Get configuration values for the language
+        input_encoding = 'utf8' #config.get(language+'_input_encoding','ascii')
+        output_encoding = 'utf8' #config.get(language+'_output_encoding','ascii')
+        show_source = True 
+
+        # Build the code text
+        code = ''.join(lines).strip()
+        filename_clean = filename.rsplit('.',1)[0]
+        if filename_clean.startswith('./') : filename_clean = filename_clean[2:]
+        #print "Running the example ....",filename_clean
+        #print "Root ?", env.doc2path(env.docname, base=None)
+
+        import subprocess as S
+        error = True
+        try : 
+            stdout =''
+            #resout = S.check_output("./example_bin/doc_%s"%(filename_clean) ,stderr=S.STDOUT,shell=True)
+            resout = S.check_output("./%s/doc_%s"%(docdir,filename_clean) ,stderr=S.STDOUT,shell=True)
+            if resout : 
+               stdout = '---------- Result is -------\n' + resout.strip()
+            error = False
+        except S.CalledProcessError as E : 
+            stdout ='---------- RunTime error -------\n'
+            stdout += E.output
+
+        # Process output 
+        if stdout:
+            stdout = stdout.decode(output_encoding,'ignore')
+            out = ''.join(stdout).decode(output_encoding)
+        else:
+            out = '' #.join(stderr).decode(output_encoding)
+        
+        # Get the original code with prefixes
+        code_out = '\n'.join((code,out))
+
+        if error : # report on console
+            print(" Error in processing ")
+            print(code_out) 
+
+        literal = nodes.literal_block(code_out,code_out)
+        literal['language'] = 'c' 
+        literal['linenos'] = 'linenos' in self.options
+        return [literal]
+
+def setup(app):
+    app.add_directive('triqs_example', TriqsExample)
+    app.connect('builder-inited',TriqsExampleRun.builder_init)
+

doc/themes/triqs/layout.html

@@ -0,0 +1,52 @@
+{#
+    layout.html
+    ~~~~~~~~~~~
+
+    TRIQS layout template heavily based on the sphinxdoc theme.
+
+    :copyright: Copyright 2013 by the TRIQS team.
+    :copyright: Copyright 2007-2013 by the Sphinx team.
+    :license: BSD, see LICENSE for details.
+#}
+{%- extends "basic/layout.html" %}
+
+{# put the sidebar before the body #}
+{% block sidebar1 %}{{ sidebar() }}{% endblock %}
+{% block sidebar2 %}{% endblock %}
+
+{% block extrahead %}
+    <link href='https://fonts.googleapis.com/css?family=Open+Sans:300,400,700' rel='stylesheet' type='text/css'>
+    <script src="{{ pathto('_static/cufon-yui.js',1) }}" type="text/javascript"></script>
+    <script src="{{ pathto('_static/spaceman.cufonfonts.js',1) }}" type="text/javascript"></script>
+    <script type="text/javascript">
+      Cufon.replace('.triqs', { fontFamily: 'spaceman', hover: true }); 
+    </script>
+{{ super() }}
+{%- if not embedded %}
+    <style type="text/css">
+      table.right { float: right; margin-left: 20px; }
+      table.right td { border: 1px solid #ccc; }
+      {% if pagename == 'index' %}
+      .related { display: none; }
+      {% endif %}
+    </style>
+{%- endif %}
+{% endblock %}
+
+{% block rootrellink %}
+    <li><a href="{{ pathto('index') }}">Home</a> &raquo;</li>
+{% endblock %}
+
+{% block header %}
+<div class="pageheader">
+  <ul>
+    {% for header_link in header_links %}
+    <li><a href="{{ pathto(header_link[1]) }}">{{ header_link[0] }}</a></li>
+    {% endfor %}
+  </ul>
+  <div>
+    <h1 style="padding:0; margin: 10px 0 0 0;"><a class="triqs" href="{{ pathto('index') }}">{{ header_title }}</a></h1>
+    <span style="font-size: 14px; margin: 0px; padding: 0px;">{{ header_subtitle }}</span>
+  </div>
+</div>
+{% endblock %}