From 009f0ea8297e00ba7b3f85a8e8702761996e16ab Mon Sep 17 00:00:00 2001 From: Michel Ferrero Date: Thu, 29 Aug 2013 17:23:40 +0200 Subject: [PATCH] Work on documentation The theme has been improved to be more flexible. Some work on the installation steps to get rid of BOOST_SOURCE_DIR. Took out the bundles. Changed the header items and added a link to documentation. --- doc/_templates/sideb.html | 5 +- doc/{authors.rst => about.rst} | 0 doc/applications.rst | 12 +-- doc/bundles.rst | 4 - doc/conf.py.in | 15 +++- doc/contents.rst | 5 +- doc/install.rst | 68 ++++++++++------- doc/installation/Ubuntu.rst | 73 ------------------- doc/installation/changelog.rst | 16 ---- doc/installation/install_options.rst | 4 +- doc/installation/linux.rst | 51 ------------- .../{install_on_osx_lion.rst => osx_lion.rst} | 31 ++------ .../{dependencies.rst => requirements.rst} | 52 +++++-------- doc/installation/ubuntu.rst | 31 ++++++++ doc/installation/wien2k_inst.rst | 27 ------- doc/{bugs.rst => issues.rst} | 4 +- doc/themes/triqs/layout.html | 17 ++--- 17 files changed, 128 insertions(+), 287 deletions(-) rename doc/{authors.rst => about.rst} (100%) delete mode 100644 doc/bundles.rst delete mode 100644 doc/installation/Ubuntu.rst delete mode 100644 doc/installation/changelog.rst delete mode 100644 doc/installation/linux.rst rename doc/installation/{install_on_osx_lion.rst => osx_lion.rst} (79%) rename doc/installation/{dependencies.rst => requirements.rst} (50%) create mode 100644 doc/installation/ubuntu.rst delete mode 100644 doc/installation/wien2k_inst.rst rename doc/{bugs.rst => issues.rst} (96%) diff --git a/doc/_templates/sideb.html b/doc/_templates/sideb.html index 6aad6bf7..e727887d 100644 --- a/doc/_templates/sideb.html +++ b/doc/_templates/sideb.html @@ -4,12 +4,9 @@ CNRS

-

TRIQS applications

+

TRIQS applications

Some applications are supported by the TRIQS collaboration, check them out! -Note that you can obtain -bundled sources -that contain both the TRIQS library and the supported applications.

diff --git a/doc/authors.rst b/doc/about.rst similarity index 100% rename from doc/authors.rst rename to doc/about.rst diff --git a/doc/applications.rst b/doc/applications.rst index 6003706f..67d88446 100644 --- a/doc/applications.rst +++ b/doc/applications.rst @@ -11,9 +11,7 @@ Wien2TRIQS is an interface to Wien2k for LDA+DMFT calculation. It allows you to turn band-structure calculations obtained from the Wien2k package to inputs to full-fledged LDA+DMFT calculations in a few lines! -| *Homepage:* ``_ -| *Documentation:* ``_ -| *Installation:* ``_ +*Homepage:* ``_ Hybridization-expansion matrix solver ------------------------------------- @@ -23,9 +21,7 @@ of a quantum impurity embedded in a conduction bath. It is based on a quantum Monte Carlo algorithm that stochastically samples the diagrams of a hybridization expansion of the partition function. -| *Homepage:* ``_ -| *Documentation:* ``_ -| *Installation:* ``_ +*Homepage:* ``_ Hubbard I solver ---------------- @@ -34,6 +30,4 @@ This solver gives the Hubbard I solution of a quantum impurity problem, i.e. it solves the atomic limit. This simple approximation allows to have very quick answer even for large multiband systems. -| *Homepage:* ``_ -| *Documentation:* ``_ -| *Installation:* ``_ +*Homepage:* ``_ diff --git a/doc/bundles.rst b/doc/bundles.rst deleted file mode 100644 index 03d409ab..00000000 --- a/doc/bundles.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. _bundles: - -Bundles -======= diff --git a/doc/conf.py.in b/doc/conf.py.in index 9884a5ff..59e6b126 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -35,7 +35,7 @@ extensions += [ 'matplotlib.sphinxext.only_directives', 'plot_directive', # 'matplotlib.sphinxext.ipython_directive', - 'ipython_console_highlighting', + # 'ipython_console_highlighting', # 'inheritance_diagram', 'numpydoc'] @@ -81,9 +81,8 @@ copyright = u'2011-2013, The TRIQS collaboration' # built documents. # # The short X.Y version. -version = '1.0' -# The full version, including alpha/beta/rc tags. -release = '1.0.0' +version = '@TRIQS_VERSION@' +release = '@TRIQS_RELEASE@' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -145,6 +144,14 @@ doxylink = { 'doxy' : ('@CMAKE_CURRENT_BINARY_DIR@/doxy.tag', 'doxy_triqs') } html_theme_path = ["@TRIQS_SOURCE_DIR@/doc/themes/"] html_theme = "triqs" html_show_sphinx = False +html_context = {'header_title': 'triqs', + 'header_subtitle': 'a Toolbox for Research on Interacting Quantum Systems', + 'header_links': [['Install', 'install'], + ['Documentation', 'documentation'], + ['Applications', 'applications'], + ['Issues', 'issues'], + ['About TRIQS', 'about'] + ]} #html_theme_options = { "pagewidth": "80em", "documentwidth" : "60em" } diff --git a/doc/contents.rst b/doc/contents.rst index d99a9244..7ea7f1b5 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -9,7 +9,6 @@ Table of contents install documentation applications - bundles - bugs - authors + issues + about diff --git a/doc/install.rst b/doc/install.rst index a16787b8..0e8736cd 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,4 +1,4 @@ -.. index:: installation steps +.. index:: installation .. highlight:: bash @@ -7,43 +7,61 @@ Installation ============ -* TRIQS is hosted on **GitHub**, where you can : +Prerequisite +------------ - * Download `the current version `_ (recommended) :: - - git clone git://github.com/TRIQS/TRIQS.git path_to_triqs_sources - - NB : this version is normally never broken (developments are done elsewhere). - - * Download `an older release `_, which may require less recent versions of compilers, libs... - - * Use the GitHub *Issues* tracker for any problem, questions. - - *Please do NOT contact the developers directly by email* - -Complete installation instructions for standard systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The TRIQS library relies on a certain number of standard libraries described in +the :ref:`list of requirements `. Here are instructions to install +these necessary libraries on two standard systems: .. toctree:: :maxdepth: 1 - installation/Ubuntu - installation/linux - installation/install_on_osx_lion + installation/ubuntu + installation/osx_lion + +Installation steps +------------------ + +#. Download the sources of TRIQS from github into a ``src`` directory:: + + $ git clone git@github.com:TRIQS/triqs.git src + +#. Create an empty build directory where you will compile the code:: + + $ mkdir build && cd build + +#. In the build directory call cmake specifying where the TRIQS library should be installed:: + + $ cmake -DCMAKE_INSTALL_PREFIX=path_to_install_directory ../src + +#. Compile the code, run the tests and install the library:: + + $ make + $ make test + $ make install + +#. After the installation TRIQS has been installed using the standard UNIX + scheme: + + * executables in ``path_to_install_directory/bin``. + + * c++ and python libraries in ``path_to_install_directory/lib``. + + * c++ headers in ``path_to_install_directory/include/triqs``. -Details -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + * shared items in ``path_to_install_directory/share/triqs``. + + +Further details +--------------- .. toctree:: :maxdepth: 1 - installation/wien2k_inst - installation/dependencies installation/python installation/clang installation/intel installation/install_options - installation/get_started installation/changelog - diff --git a/doc/installation/Ubuntu.rst b/doc/installation/Ubuntu.rst deleted file mode 100644 index 0f8c2c6a..00000000 --- a/doc/installation/Ubuntu.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. index:: Ubuntu - -.. _Ubuntu : - -.. highlight:: bash - -Installation on Ubuntu (12.04 LTS) -#################################################### - -TRIQS can be installed on Ubuntu 12.04 LTS. - -NB : Ubuntu 12.10: there is a bug in Ubuntu 12.10 (hdf5 compiled without hdf5 support). -On Ubuntu 12.10, you have to recompile hdf5. The problem has been reported and will be fixed in 13.04. - -#. Install the following packages which are necessary to build TRIQS and use it:: - - sudo apt-get install cmake git g++ libgfortran3 gfortran openmpi-bin openmpi-common \ - openmpi-checkpoint libopenmpi-dev libblas-dev liblapack-dev libfftw3-dev libgmp-dev \ - hdf5-tools libhdf5-serial-dev python-h5py libboost1.48-all-dev python-dev \ - python-numpy python-scipy python-virtualenv python-matplotlib doxygen\ - python-tornado python-zmq - -#. Download the code:: - - git clone git://github.com/TRIQS/TRIQS.git path_to_triqs_sources - -#. Create a build directory (different from the TRIQS source directory nor a subdirectory thereof) :: - - mkdir triqs_build && cd triqs_build - -#. Configure :: - - cmake path_to_triqs_sources -DCMAKE_INSTALL_PREFIX=path_to_install_directory - - NB: the install directory is optional and defaults to `triqs_build/INSTALL_DIR`. It is - however usually a good idea to have an install directory outside `triqs_build` (after - a successful installation `triqs_build` can be deleted). The cmake call should end with:: - - -- Build files have been written to: *path_to_triqs_build* - - OPTIONAL: To install the documentation, install Sphinx and doxygen: :: - - sudo easy_install -U Sphinx - sudo apt-get install doxygen - - and add:: - - -DBuild_Documentation=ON - - to the above cmake command. - -#. Build TRIQS, test it and install it with (N being the number of cores of your machine) :: - - make -jN && make test && make -jN install - - NB: the tests SingleSite and CDMFT-v2 take longer than the other ones (30s to 1 min). - -#. If you use Wien2TRIQS, please complete the installation as described :ref:`here `. - - - - -#. You can now :ref:`start ... ` - -#. Optionally, you may be interested in: - - * How to *simply* upgrade the ipython notebook with :ref:`virtualenv ` to the latest version? - - * How to use the nice :ref:`clang ` C++ compiler? - - * How to use :ref:`Intel ` C++ compiler? - -.. warning:: For the branch 1.0, you need the latest version of Cython (>=.17, downloadable on Cython.org). If Cython is not found, specify the location of the executable with the option -DCYTHON_EXECUTABLE. diff --git a/doc/installation/changelog.rst b/doc/installation/changelog.rst deleted file mode 100644 index f63678a5..00000000 --- a/doc/installation/changelog.rst +++ /dev/null @@ -1,16 +0,0 @@ -Changelog between releases -======================================= - -v0.9 -> current ------------------- - -* Now use to C++11. - - -v0.8 -> v0.9 -------------- - -* To be written - - - diff --git a/doc/installation/install_options.rst b/doc/installation/install_options.rst index bc5ad6d5..1fd54531 100644 --- a/doc/installation/install_options.rst +++ b/doc/installation/install_options.rst @@ -4,8 +4,8 @@ .. _install_options: -Customizing installation : cmake options ----------------------------------------------------- +Customizing installation: cmake options +--------------------------------------- Specifying the compiler or compile/link flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/installation/linux.rst b/doc/installation/linux.rst deleted file mode 100644 index d8dea646..00000000 --- a/doc/installation/linux.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. index:: Linux - -.. _Linux: - -.. highlight:: bash - -Installation on a generic Linux distribution -####################################################### - -TRIQS has been installed successfully on several distributions. - -#. Download the code (this is for the current development version) :: - - git clone git://github.com/TRIQS/TRIQS.git path_to_triqs_sources - -#. Download the `sources of boost `_ and untar them into ``path_to_boost_sources``. - **Don't compile boost**. - -#. Create a build directory (different from the TRIQS source directory nor a subdirectory thereof) :: - - mkdir triqs_build && cd triqs_build - -#. Configure :: - - cmake path_to_triqs_sources -DBOOST_SOURCE_DIR=path_to_boost_sources \ - -DCMAKE_INSTALL_PREFIX=path_to_install_directory - - [NB : the install directory is optional, the default value is `triqs_build/INSTALL_DIR`] - - Successful run of cmake will finish with :: - - -- Build files have been written to: *path_to_triqs_build* - -#. Build TRIQS, test it and install it with (N being the number of cores of your machine) :: - - make -jN && make test && make -jN install - - [NB : the tests SingleSite and CDMFT-v2 take longer than the other ones (30s to 1 min) ]. - -#. If you use Wien2TRIQS, please complete the installation as described :ref:`here `. - -#. You can now :ref:`start ... ` - -#. Optionally, you can be interested in : - - * How to *simply* upgrade the ipython notebook with :ref:`virtualenv ` to the latest version ? - - * How to use the nice :ref:`clang ` C++ compiler ? - - * How to use :ref:`Intel ` C++ compiler ? - diff --git a/doc/installation/install_on_osx_lion.rst b/doc/installation/osx_lion.rst similarity index 79% rename from doc/installation/install_on_osx_lion.rst rename to doc/installation/osx_lion.rst index 86772be8..2d6da7a9 100644 --- a/doc/installation/install_on_osx_lion.rst +++ b/doc/installation/osx_lion.rst @@ -3,10 +3,11 @@ .. _install_on_osx_lion: .. highlight:: bash -Installation on Mac OS X [Mountain Lion] -============================================== +Installing required libraries on Mac OS X +========================================= -This installation guide may work for older versions of Mac OS X. However, previous versions of Mac OS X are not supported. +This installation guide has been tried on Mountain Lion. It may work for older +versions of Mac OS X but previous versions of Mac OS X are not supported. NB: The installation of TRIQS under previous versions of OS X requires installing clang (via Xcode) or gcc 4.7 (via MacPorts). On Mountain Lion, clang (llvm) replaces gcc 4.2 as the default C++ compiler. @@ -15,7 +16,7 @@ We strongly recommend the following installation procedure, which provides a cle of them are compatible with each other. Only the installation via homebrew is supported for the Mac. Installation of the dependencies -________________________________ +-------------------------------- 1. Install `homebrew `_. @@ -76,26 +77,8 @@ NB : you need pyparsing <=1.5.7 since apparently v.2.0 works only for python 3. 7. Download the latest `sources of boost `_ and untar them into a directory ``BOOST_SRC``. - -TRIQS installation -__________________ - -#. Download the TRIQS sources: :: - - git clone git@github.com:TRIQS/TRIQS.git TRIQS_src - -#. Generate a Makefile using cmake: :: - - cmake TRIQS_src -DBOOST_SOURCE_DIR=BOOST_SRC - -#. Compile TRIQS, its tests and install it into INSTALL_DIR (default) (N is the number of cores of your mac): :: - - make -jN && make test && make install - -#. If you use Wien2TRIQS, please complete the installation as described :ref:`here `. - -Possible issues: -________________ +Possible issues +--------------- If you encounter the following error: :: diff --git a/doc/installation/dependencies.rst b/doc/installation/requirements.rst similarity index 50% rename from doc/installation/dependencies.rst rename to doc/installation/requirements.rst index c79086ff..9d0a75b4 100644 --- a/doc/installation/dependencies.rst +++ b/doc/installation/requirements.rst @@ -1,42 +1,42 @@ -.. index:: dependencies +.. index:: required libraries -.. _dependencies: +.. _requirements: -A complete list of dependencies -================================== +A complete list of requirements +================================ -TRIQS is built upon several python and C++ libraries, which, if not present already in your system, can be freely downloaded and installed. -All the libraries and tools used by TRIQS are listed in the table : +TRIQS is built upon several python and C++ libraries, which, if not present +already in your system, can be freely downloaded and installed. All the +libraries and tools used by TRIQS are listed in the table: ================== ================ ================================================================================ Libraries/tools Version Comment ================== ================ ================================================================================ mpi e.g., openmpi Parallelism - Since standard linux distributions (and macports on OS X) now provides openmpi, even on laptops, we avoid the unnecessary complication of maintaining a non parallel version of TRIQS fftw >= 3.2 Fourier transform boost >= 1.49 C++ librairies hdf5 >= 1.8.0 File storage system. Important: the *serial* version must be installed -python* >= 2.6.5 -scipy* python mathematical library -numpy* python scientific library -h5py* python interface to hdf5 library -sphinx* >= 1.0.1 python documentation tools (to compile documentation) -pyparsing* Tool for sphinx (to compile documentation) -matplotlib* >= 0.99 python 2D plotting library -cython >=0.17 [DEVELOPERS ONLY] +python >= 2.6.5 +scipy python mathematical library +numpy python scientific library +h5py python interface to hdf5 library +sphinx >= 1.0.1 python documentation tools (to compile documentation) +pyparsing Tool for sphinx (to compile documentation) +matplotlib >= 0.99 python 2D plotting library +cython >=0.17 cython package ================== ================ ================================================================================ - \* designates the libraries included in the Enthought python distribution. +\* designates the libraries included in the Enthought python distribution. C++11 --------- +----- The current version of TRIQS use the new C++11 standard, and therefore require a recent C++ compiler. -Tested compilers include : +Tested compilers include: * g++ 4.6.3, 4.7 * clang++ 3.1 @@ -47,22 +47,10 @@ Note that older compilers will *never* be supported for current and future versi Older releases may accept older compilers. F90 -------- +--- For the Wien2TRIQS interface only. -Tested compilers include : +Tested compilers include: * ifort * gfortran - -Boost --------------------------- - -The boost library is often upgraded, and it is rare to have the correct version in your distribution. TRIQS installation process offers two choices : - - * Recommended choice: As explained in the :ref:`page above `, you can download simply the latest *sources* and TRIQS will do all the job for you by compiling the pieces of boost that are needed in a little boost_for_triqs library. - - * OR you can include and link with an installed boost if the version if high enough as discussed in :ref:`install_options`. - - - diff --git a/doc/installation/ubuntu.rst b/doc/installation/ubuntu.rst new file mode 100644 index 00000000..a1fd8539 --- /dev/null +++ b/doc/installation/ubuntu.rst @@ -0,0 +1,31 @@ +.. index:: ubuntu + +.. _Ubuntu : + +.. highlight:: bash + +Installing required libraries on Ubuntu +======================================= + +TRIQS has been installed and tested on Ubuntu 12.04 and 13.04. Note that there +is a bug in Ubuntu 12.10 (the hdf5 library has been compiled without hdf5 +support) so if you are using that version you will have to recompile the hdf5 +library. The problem has been reported and is fixed in 13.04. + +Install the following packages which are necessary to build TRIQS and use it:: + + sudo apt-get install cmake git g++ libgfortran3 gfortran openmpi-bin openmpi-common \ + openmpi-checkpoint libopenmpi-dev libblas-dev liblapack-dev libfftw3-dev libgmp-dev \ + hdf5-tools libhdf5-serial-dev python-h5py libboost1.48-all-dev python-dev \ + python-numpy python-scipy python-virtualenv python-matplotlib doxygen\ + python-tornado python-zmq + +Optionally, you may be interested in: + + * How to *simply* upgrade the ipython notebook with :ref:`virtualenv ` to the latest version? + + * How to use the nice :ref:`clang ` C++ compiler? + + * How to use :ref:`Intel ` C++ compiler? + +.. warning:: you need the latest version of Cython (>=.17, downloadable on Cython.org). If Cython is not found, specify the location of the executable with the option -DCYTHON_EXECUTABLE. diff --git a/doc/installation/wien2k_inst.rst b/doc/installation/wien2k_inst.rst deleted file mode 100644 index aa337cb7..00000000 --- a/doc/installation/wien2k_inst.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. index:: wien2k_inst - -.. _wien2k_inst: - -Complete the installation of Wien2TRIQS (all platforms) -------------------------------------------------------------- - -If you choose to install the Wien2TRIQS interface to the Wien2K package for doing DMFT calculations of -realistic systems, you need take the last steps manually since Wien2k installation is not standard on all machines. -During TRIQS installation several files will be will be put into :: - - path_to_TRIQS_install_directory/share/triqs/Wien2k_SRC_files/SRC_templates - -Those files are:: - * :file:`case.cf_f_mm2` and :file:`case.cf_p_cubic` containing matrices for the complex->cubic transformation of the local angular basis - - * :file:`case.indmftpr` is a template for the input file needed by the :program:`dmftproj` program. This program constructs a set of localized orbitals representing correlated states. - -These files then have to be copied manually to :file:`path_to_Wien2k/SRC_templates`, where :file:`path_to_Wien2k` is the path to Wien2K main directory. - -When building the Wien2k extension module, TRIQS will compile :program:`dmftproj` and install it into :file:`path_to_TRIQS_install_directory/bin`. - -In addition, :file:`path_to_Wien2k/SRC_templates` also contains :program:`run_triqs` and :program:`runsp_triqs` scripts for running Wien2k+DMFT fully self-consistent calculations. These files should be copied to :file:`path_to_Wien2k`. - -You will also need to insert manually a correct call of :file:`pytriqs` into these scripts using an appropriate for your system MPI wrapper (mpirun, mpprun...), if needed. Search for *pytriqs* within the scripts to locate the appropriate place for inserting the :file:`pytriqs` call. - -Finally, you will have to change the calls to :program:`python_with_DMFT` to :program:`pytriqs` in the Wien2k :file:`path_to_Wien2k/run*` files. diff --git a/doc/bugs.rst b/doc/issues.rst similarity index 96% rename from doc/bugs.rst rename to doc/issues.rst index 9753917f..a5b32be4 100644 --- a/doc/bugs.rst +++ b/doc/issues.rst @@ -1,6 +1,6 @@ -Reporting bugs -============== +Reporting issues +================ Please report all problems and bugs directly at the github issue page ``_. In order to make it easier diff --git a/doc/themes/triqs/layout.html b/doc/themes/triqs/layout.html index f2c03ddc..bd38fbd6 100644 --- a/doc/themes/triqs/layout.html +++ b/doc/themes/triqs/layout.html @@ -34,24 +34,19 @@ {% endblock %} {% block rootrellink %} - {% if hasdoc('documentation') %} -
  • Home »
    • - {% else %} -
  • Documentation »
    • - {% endif %} +
  • Home »
    • {% endblock %} {% block header %}
    -

    TRIQS

    - a Toolbox for Research on Interacting Quantum Systems +

    {{ header_title }}

    + {{ header_subtitle }}
    {% endblock %}