Initial commitv1.2

1 files changed, 221 insertions, 0 deletions

diff --git a/man/meankondo.1 b/man/meankondo.1
new file mode 100644
index 0000000..ea4814b
--- /dev/null
+++ b/man/meankondo.1
@@ -0,0 +1,221 @@
+.Dd $Mdocdate: April 13 2015 $
+.Dt meankondo 1.2
+.Os
+.Sh NAME
+.Nm meankondo
+.Nd A tool to compute renormalization group flows for Fermionic hierarchical models
+.Sh SYNOPSIS
+.Nm
+.Op Fl t Ar threads
+.Op Fl C
+.Op Ar config_file
+.Pp
+.Nm
+.Fl v
+.Sh DESCRIPTION
+.Nm
+computes the renormalization group flow equations for Fermionic hierarchical models, which should be defined in the configuration file provided on the command line, following the syntax detailed below.
+.Pp
+The flow equation is computed by calculating the mean of a polynomial of fields and running coupling constants using the Wick rule and a propagator provided in the configuration file. The running coupling constants are then identified in the resulting polynomial using an idtable provided in the configuration file.
+.Pp
+.Nm
+is part of a set of tools to compute and manipulate Fermionic hierarchical flows:
+.Bl -bullet
+.It
+.Sy meankondo
+: computes flow equations for hierarchical Fermionic models
+.It
+.Sy numkondo
+: numerical evaluation of flow equations.
+.It
+.Sy meantools, meantools-convert
+: perform various operations on flow equations (derivation, exponentiation, evaluation and conversion to other formats).
+.El
+.Pp
+as well as the following pre-processors, which generate configuration files for their associated model:
+.Bl -bullet
+.It
+.Sy kondo_proprocess
+:  Kondo model
+.El
+.Pp
+.Sh COMMAND-LINE ARGUMENTS
+.Bl -tag -width Ds
+.It Fl t Ar threads
+The number of threads to use for the computation.
+.It Fl C
+Format the ouptput so it can be piped to
+.Sy numkondo ,
+that is, instead of printing the flow equation, print a full configuration file containing the flow equation as well as all the other entries of the configuration file that do not pertain to the computation of the flow equation.
+.It Fl v
+Print version information and exit.
+.El
+.Pp
+.Sh CONFIGURATION FILE
+.Nm
+reads a configuration file, that can either be passed as a command line argument or to stdin, which specifies the model for which to compute the flow equation.
+.Pp
+A configuration file is a list of entries, separated by a '&' character, each of which has a title (or header), which is preceded by '#!'. Note that '#!' must be at the beginning of a line in order to be read correctly.
+.Pp
+Whenever the '#' character is encountered, the rest of the line is treated as a comment and ignored (unless it is followed by '!').
+.Pp
+As a general rule, spaces and line breaks in the entries of the configuration file are ignored, so they may be used at the user's discretion. The few entries that require that no extra line breaks be inserted are explicitly mentioned below.
+.Pp
+.Nm
+recognizes the following entries (unless explicitly mentioned, the entries below are mandatory) (entries may be provided in any order) (any extra entries in the configuration file are ignored):
+.Bl -tag -width Ds
+.It Sy #!fields
+A list of the fields of the model.
+.Pp
+The fields entry contains 4 lines which start with 'i:', 'x:', 'h:' and 'f:'. Each of these is followed by a ',' separated list of field indices, which are positive integers.
+.Bl -bullet
+.It
+The indices following 'i' correspond to internal fields, which are integrated out using the Wick rule and the propagator provided in the '#!propagator' entry. Each internal field is associated a conjugate field, whose index is the opposite of the field's index (e.g. 'i:101' defines a field whose index is -101)
+.It
+The indices following 'x' correspond to external fields that are associated conjugate field (e.g. 'x:100' defines a field whose index is -100). External indices may not appear as internal indices.
+.It
+The indices following 'h' correspond to external fields that are not associated a conjugate field. External indices may not appear as internal indices.
+.It
+The 'f' line specifies which of the internal and external indices are Fermions, i.e. which fields anti-commute. The fields appearing in the 'f' line should also either appear in the 'i' or 'x' line. WARNING: for the moment, only cases in which all of the internal fields are Fermions are supported.
+.El
+.Pp
+.Em Line breaks are not ignored in this entry.
+.Pp
+Example:
+.D1 i:101,102,201,202
+.D1 x:100,200
+.D1 h:301,302,303
+.D1 f:100,101,102
+.It Sy #!propagator
+The propagator of the model.
+.Pp
+The propagator entry is a ',' separated list whose elements are of the form
+.D1 index1;index2: polynomial
+where index1 and index2 are internal indices, and polynomial is a polynomial (see the POLYNOMIALS section below for information on how to format polynomials). The polynomial must not depend on the internal fields. Note that a number is a special type of polynomial, so propagators with numerical entries are handled by
+.Nm
+just as easily as propagators with symbolic entries. Such an entry means that
+.D1 <psi_{index1}^-psi_{index2}^+> = polynomial.
+.Pp
+Example:
+.D1 101;102: 1 , 102;101: -1 , 201;202: s{-1} + (-1)[l10] , 202;201: (-1)s{-1} + [l10]
+.It Sy #!symbols
+Symbolic variables used as shortcuts for more complicated expressions (optional entry).
+.Pp
+In order to simplify long expressions, symbolic variables can be defined in this entry. Each variable is assigned an index, which is a positive integer that must be different from any of the internel and external indices defined in the '#!fields' entry.
+.Pp
+The symbols entry is a ',' separated list, whose elements are of the form
+.D1 index= polynomial
+where index is the index of the variable and polynomial is the expression it stands for (see the POLYNOMIALS section below for information on how to format polynomials). Note that polynomial can contain other symbolic variables. There is no safeguard against self-referencing definitions that may cause infinite loops.
+.Pp
+Example:
+.D1 1001= (-1)[f-100][f100] + (-1)[f-101][f101] , 2001=[f-100][f100] + [f-201][f201]
+.Pp
+This entry is optional.
+.Pp
+.It Sy #!identities
+Identities satisfied by some of the fields (optional entry).
+.Pp
+In some cases, some of the quantities involved in a model will satisfy an identity (e.g. a vector may be of unit-norm), which should simplified out from the flow equation.
+.Pp
+The identities entry is a ',' separated list, whose elements are of the form
+.D1 monomial=polynomial
+where monomial represents the left side of the identity and is a sequence of field indices of the form '[f index1][f index2]...' and polynomial represents the right side of the identity (see the POLYNOMIALS section below for information on how to format polynomials).
+.Pp
+Example:
+.D1 [f301][f301]=(1)+(-1)[f302][f302]+(-1)[f303][f303]
+.Pp
+This entry is optional.
+.Pp
+.It Sy #!input_polynomial
+The polynomial whose mean we wish to compute in order to calculate the flow equation.
+.Pp
+The format of the polynomial is that specified in the POLYNOMIALS section. In addition, the polynomial can be specified as the product of other polynomials:
+.D1 polynomial1 * polynomial2 * ...
+Note that there are no parentheses, and therefore, products cannot be nested, nor can a product of polynomials be summed with another polynomial.
+.Pp
+Example:
+.D1 (1) + (1/2)[l1][f1001] * (1) + (1/2)[l2][f2001]
+.It Sy #!id_table
+The idtable used to identify the running coupling constants.
+.Pp
+Once the mean of the input polynomial has been computed, we are left with a polynomial of the external fields and the running coupling constants that were in the input polynomial. In order to compute a flow equation from this average,
+.Nm
+uses an idtable to identify which of the monomials of the average contribute to which running coupling constant.
+.Pp
+The id_table entry is a ',' separated list, whose elements are of the form
+.D1 rcc: polynomial
+where rcc is the index of the corresponding running coupling constant, which is a non-negative integer, and polynomial is the polynomial to which rcc refers to (which is a polynomial of the external fields).
+.Pp
+Example:
+.D1 1:(-1)[f-100][f100] , 2:[f-200][f200]
+.It Sy #!groups
+Groups of independent variables (optional entry).
+.Pp
+In order to speed up the computation of the mean of the input polynomial, groups of independent variables can be specified. When
+.Nm
+computes the mean of a monomial containing elements of different groups, it factors the monomial into independent factors, computes the mean of each factor, and then takes their product. This way,
+.Nm
+does not repeatedly try to pair independent fields.
+.Pp
+The groups entry is a list of collections of fields or symbols of the following form
+.D1 (index1,index2,...)
+.Pp
+Example:
+.D1 (1001,1002) (2001,2002)
+.Pp
+.Em Warning:
+.Nm
+does not check that the fields in different groups are truly independent, so cases in which fields in different group have a non-vanishing propagator entry may give unexpected results.
+.Pp
+This entry is optional.
+.El
+.Pp
+.Sh NUMBERS
+.Nm
+can parse rational numbers and linear combinations of square roots of integers (positive or negative (which is how complex numbers are implemented)) with rational coefficients (i.e. elements of the field extension of Q generated by sqrt(Z)).
+.Pp
+A number is a '+' separated list whose elements are of the form
+.D1 (a/b)s{r}
+where a and r are integers and b is a positive integer. s{r} stands for sqrt(r).
+.Pp
+If a=b, then the number may be written as 's{r}'. If b=1, then it can be '(a)s{r}'. If r=1, then it can be 'a/b'. If b=r=1, then it can be 'a'.
+.Pp
+Example:
+.D1 (1/2)s{2} + (-1)s{-1} + 3/2
+.Pp
+.Sh POLYNOMIALS
+Polynomials are '+' separated lists of monomials. Each monomial is a sequence of numbers, rccs and fields.
+.Bl -bullet
+.It
+Numbers are enclosed between '(' and ')'. If there are several numbers in a monomial, then they are multiplied.
+.It
+rccs are non-negative indices enclosed between '[l' and ']'.
+.It
+Fields are non-vanishing indices enclosed between '[f' and ']'. Fields must either appear in the '#!fields' entry or the '#!symbols' entry.
+.El
+.Pp
+If the numerical factor of a monomial is 1, then it can be dropped. However, even if the numerical factor is a single integer, its '(' and ')' delimiters cannot be omitted.
+.Pp
+Example:
+.D1 (1) + ((3/2)s{2} + (-1)s{-1} + 3)[l1][l2][f100][f1001][f101] + [l1][f101] + (3)[l2]
+.Pp
+.Sh OUTPUT
+.Nm
+prints the flow equation to stdout.
+.Pp
+The rccs in the flow equation are of the form '[% index]' and the constant term in the flow equation is denoted by '[C1]'. The factor '[/C1^power]' stands for (1/C1^power).
+.Pp
+.Sh KNOWN ISSUES
+.Nm
+only supports models in which all of the internal fields are Fermions.
+.Pp
+.Sh RETURN CODE
+.Nm
+returns 0 on success and -1 on error.
+.Pp
+.Sh SEE ALSO
+.Sx numkondo Ns (1) ,
+.Sx meantools Ns (1) ,
+.Sx meantools-convert Ns (1) ,
+.Sx kondo_preprocess Ns (1)
+.Pp