3
0
mirror of https://github.com/triqs/dft_tools synced 2024-12-25 05:43:40 +01:00

Restructuring documentation.

A first general restructuration of the doc according to the pattern [tour|tutorial|reference].
In the reference part, objects are documented per topic.
In each topic, [definition|c++|python|hdf5] (not yet implemented)
This commit is contained in:
tayral 2014-10-17 17:15:19 +01:00
parent a9e5f20c39
commit edd1ff4529
316 changed files with 519 additions and 696 deletions

View File

@ -53,8 +53,9 @@ ENDFOREACH()
endmacro()
# Dive and find the doxygen sources
add_subdirectory(reference/c++)
add_subdirectory(tutorials/c++)
add_subdirectory(reference/)
add_subdirectory(tutorials/)
add_subdirectory(tour/)
# Build the doxygen
set(DOXYGEN_HTML_OUTPUT ./html/doxy_triqs)

View File

@ -6,22 +6,68 @@ Documentation
A quick tour
------------
A little tour of some aspects of TRIQS and its applications, at the Python level.
.. toctree::
:maxdepth: 1
tutorials/python/contents
tutorials/c++/contents
tour/getting_started/get_started
tour/green
tour/tight_binding
tour/ctqmc
tour/dmft
tour/ipt
Tutorials
----------
Learn how to use TRIQS step by step, both in Python and c++ !
.. toctree::
:maxdepth: 1
tutorials/gfs_tutorial
tutorials/array_tutorial
tutorials/det_manip_tutorial
Reference manual
-----------------
This is the reference manual for the Python and the C++ libraries.
.. toctree::
:maxdepth: 1
reference/using_the_lib/contents
Code reference
~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
reference/gfs/contents
reference/lattice_tools/contents
reference/plotting_protocols/contents
reference/montecarlo/contents
reference/operators/contents
reference/random_generator/contents
reference/arrays/contents
reference/clef/contents
reference/hdf5/contents
reference/determinant_manipulation/contents
reference/statistical_analysis/contents
Developer tools
~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 2
:maxdepth: 1
reference/python/contents
reference/c++/contents
reference/conventions
reference/using_the_lib/profiling
reference/wrap_generator/contents
reference/utilities/contents
Version compatibility
---------------------

View File

@ -1,4 +1 @@
add_all_subdirectories_with_cmakelist()

View File

@ -1,22 +0,0 @@
C++
=============
.. warning::
This documentation is work in progress.
.. toctree::
:maxdepth: 1
conventions
using_the_lib/contents
arrays/contents
gf/contents
clef/contents
mctools/intro
det_manip/contents
parameters/parameters
statistics/contents
utilities/contents
using_the_lib/profiling

View File

@ -1,5 +0,0 @@
# Doxygen sources
set_property(GLOBAL APPEND PROPERTY DOXYGEN_SOURCES ${TRIQS_SOURCE_DIR}/triqs/parameters/parameters.hpp)
all_tests()

View File

@ -1,141 +0,0 @@
Parameters
===============
.. warning::
Library of beta quality.
Documentation : just intro/tutorial, reference doc in progress.
Introduction
--------------
The purpose of the class parameters is to handle program input parameters.
It provides a convenient way to pass several parameters of different types to a program.
Parameters can be stored in a parameters object and accessed in a manner which is reminiscent of a Python dict:
.. code-block:: c
parameters P;
P["x"] = 3.14;
y = P["x"];
In Python the syntax is similar:
.. code-block:: python
import parameters as params
P = params.Parameters()
P['x'] = 3.14
y = P['x']
The class implements the following features:
* storage of parameters of any type, including arrays
* C-like cast operations, such as integral type to double conversion as well as lexical cast to arithmetic types
* Python interface
* type checking
* hdf5 I/O operations
* write contents to std::ostream
* the class is boost-serializable
parameter_defaults
-----------------------------
When parameters are used within a program, a number of them are usually optional, in
the sense that they need not be provided by the user. This either means that the program
can run without them, or meaningful default values can be provided.
Other parameters, on the other hand, may be required to be provided by the user.
These typically are parameters for which one cannot provide meaningful default values.
These cases can be handled in a consistent manner using the parameter_defaults class.
An object of this class allows to specify the name, type and documentation for all
required and optional parameters. Default values are provided for optional parameters:
.. code-block:: c
parameter_defaults pdef;
pdef.required("Beta", double(), "Inverse temperature")
.optional("N_time", int(100), "Number of time points")
.optional("N_freq", int(200), "Number of frequencies")
;
The default_parameters object serves two main purposes: Firstly, the input parameters can
be checked for completeness and correctness, i.e. they can be checked if all required parameters
are provided and have correct type.
Secondly, the optional parameters provided through the input parameters can be checked whether they
have correct type. Those which are not provided can be added to the input parameter set with
their respective default values.
Both steps are performed through the update method of the parameter class:
.. code-block:: c
parameters P;
P["Beta"] = 3.14;
P.update(pdef);
Given that the parameter_defaults are complete, the resulting parameter object contains all
parameters that the program will eventually access.
Finally, the information stored in the defaults can be used to generate the help of the program,
by printing a list of its parameters:
.. code-block:: c
std::cout<<pdef<<std::endl;
See below for more detailed working code examples.
For detailed information on how to use the parameter and parameter_defaults classes within a program, refer to the **TRIQS solver coding guidelines**.
Headers
--------------
The parameter class and the parameter_defaults class are declared in the header
triqs/utility/parameters.hpp
Doxygen documentation
-------------------------
The :doxy:`full C++ parameter documentation<triqs::utility::parameters>` and
the :doxy:`parameter_defaults documentation<triqs::utility::parameter_defaults>` are available here.
Parameter example
-------------
.. triqs_example:: ./parameters_0.cpp
Parameter default value example
-------------
.. triqs_example:: ./parameters_1.cpp
Python example
-------------
.. code-block:: python
import parameters as params
P = params.Parameters()
P['num'] = 2.3
P['str'] = "hello world"
print P
dct = { 'a' : 10, 'b' : "a string"}
P.update(dct) # update from a dictionary
print P
import numpy as np
a = np.array([[1,2],[3,4]])
P['A'] = a # add an array
print P
P.update2( c = 4, d= "u") # update from an initializer list
print P

View File

@ -1,28 +0,0 @@
#include <triqs/parameters.hpp>
using triqs::params::parameters;
#include <triqs/arrays.hpp>
int main() {
parameters P;
/*
P["a"] = long(1);
P["d"] = 2.7;
P["a_string"] = std::string("-14.3");
P["char_string"] = "-14.3";
triqs::arrays::array<double, 2> A(2, 2);
A() = 0;
A(0, 0) = 1.3;
A(1, 1) = -8.2;
P["A"] = A;
std::cout << "A:" << P["A"] << std::endl;
long a = P["a"];
double x = P["a"]; // cast to double from long
double y = P["a_string"]; // lexical cast to double from string
std::cout << y << std::endl;
*/
return 0;
}

View File

@ -1,19 +0,0 @@
#include <triqs/parameters.hpp>
using triqs::params::parameters;
int main() {
/*
parameters P;
P["Beta"] = 3.14;
parameter_defaults pdef;
pdef.required("Beta", double(), "Inverse temperature").optional("Alpha", int(1000), "An integer").optional("Gamma", double(0.9),
"A double");
std::cout << pdef << std::endl; // print a comprehensive list of parameters:
std::cout << P << std::endl;
P.update(pdef); // check whether required parameters are present and update optional ones
std::cout << P << std::endl;
*/
}

Some files were not shown because too many files have changed in this diff Show More