meankondo/man/meankondo.1

.Dd $Mdocdate: June 6 2022 $
.Dt meankondo 1.5
.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 Fl p
.Op Fl A
.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 (differentiation, products, sums, exponentials and logarithms of flow equations, evaluation and conversion to other formats).
.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 output 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 p
Print the progress of the computation.
.It Fl A
Compute the average of the effective potential, but do not write the result as a 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 5 lines which start with 'i:', 'x:', 'h:', 'f:' and 'a:'. 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 two fields whose indices are 101 and -101).
.It
The indices following 'x' correspond to external fields that are associated conjugate field (e.g. 'x:100' defines two fields whose indices are 100 and -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.
.Pp
WARNING: only cases in which all of the internal fields are Fermions are supported.
.It
The 'a' line specifies a list of external fields listed in the 'h' entry that do not commute with each other. Specifying fields in this entry will prevent
.Nm
from sorting them. These fields may not be in the 'i', 'x' or 'f' entries. This entry can be used to treat cases in which the coefficients of the input polynomial are operators that do not commute. Their commutation relations may be specified in the '#!identities' entries (see below).
.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,401,402,403
.D1 f:100,101,102
.D1 a:401,402,403
.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
Note that if the entries of the propagator are numbers instead of polynomials, then the Wick rule is implemented using a determinant instead of a sum over permutations, which is a lot faster for large monomials. Since the efficient computation of determinants requires divisions, polynomial entries in the propagator make the computation awkward, and
.Nm
falls back to implementing the Wick rule as a sum over permutations.
.Pp
Example:
.D1 101;102: 1 , 102;101: -1 , 201;202: s{-1} + (-1)[l10] , 202;201: (-1)s{-1} + [l10]
.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.
.Pp
.It Sy #!preprocessor_variables
In order to simplify configuration files, symbolic variables can be defined. When
.Nm
reads the configuration file, it replaces every variable with its value (a process which is referred to as "preprocessing").
.Pp
The preprocessor_variables entry is a ',' separated list, whose elements are of the form
.D1 variable_name=value
where 'variable_name' is a string that is not 'OUT', 'FLOW' or 'RCC', and may not contain any of the following characters: '$', '<', '>', '*', '+', '%'; and 'value' is a polynomial, formatted as described in the POLYNOMIALS section. The variable names 'OUT' 'FLOW' and 'RCC' are reserved and cannot be used. Note that 'value' can contain other preprocessor variables. There is no safeguard against self-referencing definitions that may cause infinite loops.
.Pp
A variable can be used throughout the configuration file by using the format '<$variable_name>'. Whenever '<$variable_name>' is encountered, it is replaced by its corresponding value. The order in which the variables are defined is irrelevant, since
.Nm
reads all variables definitions before replacing variables in the configuration file.
.Pp
Spaces surrounding the variable name are ignored.
.Pp
Example:
.D1 psi1 = [f1]+[f-1],
.D1 psi2 = [f2]+[f-2],
.D1 A = <$psi1>*<$psi2>
.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, or non-commuting objects may satisfy non-trivial commutation relations), which should be 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
Identities could be used to reproduce the functionality of preprocessor variables, though it is less convenient (see COMMENT ON PREPROCESSOR VARIABLES, IDENTITIES AND VIRTUAL FIELDS).
.Pp
Example:
.D1 [f301][f301]=(1)+(-1)[f302][f302]+(-1)[f303][f303],
.D1 [f401][f401]=(1),
.D1 [f401][f402]=(s{-1})[f403],
.D1 [f401][f403]=((-1)s{-1})[f402]
.Pp
This entry is optional.
.Pp
.It Sy #!virtual_fields
Virtual fields are used to keep the memory footprint of
.Nm
small, even when the input polynomial contains many terms.
.Pp
Every term of the input polynomial is parsed and stored when the configuration file is read, which may require large amounts of memory. In order to avoid this, some terms of the input polynomial can be grouped together and stored as a single virtual field, which only occupies as much memory as a single field.
.Pp
A virtual field is identified by an index, which must be different from those of the fields defined in the '#!fields' entry.
.Pp
The virtual_fields entry is a ',' separated list, whose elements are of the form
.D1 index= polynomial
where 'index' is the index of the virtual_field 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 virtual fields. There is no safeguard against self-referencing definitions that may cause infinite loops.
.Pp
WARNING: Virtual fields are assumed to commute with each other and all other Fermions. They should therefore not represent quantities that do not commute (e.g. odd monomials of Fermions or non-commuting objects specified in the 'a:' entry in the '#!fields' entry).
.Pp
Virtual fields could be used to reproduce the functionality of commuting preprocessor variables (see COMMENT ON PREPROCESSOR VARIABLES, IDENTITIES AND VIRTUAL FIELDS).
.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 #!id_table
The idtable is 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
This entry is optional.
.It Sy #!postprocess_operation
An operation that is done after having computed the mean of the input polynomial. (optional entry)
.Pp
The format of this entry is a polynomial, as specified in the POLYNOMIALS section.
.Pp
When this entry is present in the configuration, 
.Nm
creates a preprocessor variable named 'OUT', which contains the mean of the input polynomial, and can be used in the postprocessing.
.Pp
Example:
To multiply the mean of the input polynomial by 8:
.D1 <<8>*<$OUT>>
.Pp
This entry is optional.
.It Sy #!postprocess_flow_equation
This entry is similar to 'posprocess_operation', except that the operation is performed on the flow equation, that is, it is performed after having grouped the polynomial. (optional entry)
.Pp
The main difference with carrying out the operation in this way is that the constant term gets handles differently. Whereas 'postprocess_operation' gets applied to the entire polynomial, 'postprocess_flow_equation' is applied to each running coupling constant in the flow equation except the constant term. This is quite useful when the operation is not a polynomial function, such as log_1 or exp.
.Pp
The format of this entry is a polynomial, as specified in the POLYNOMIALS section.
.Pp
When this entry is present in the configuration, 
.Nm
creates a preprocessor variable named 'FLOW', which contains the polynomial obtained by adding each term in the id_table, and can be used in the postprocessing.
.Pp
Example:
To take the logarithm of the flow equation:
.D1 <%log_1<$FLOW>>
.Pp
This entry is optional.
.It Sy #!numerical_postprocess_operation
An operation that is done at each step of an eventual numerical computation done with numkondo. (optional entry)
.Pp
This is similar in spirit to the 'postprocess_flow_equation' entry, except that the postprocessing is entirely numerical (no symbolic operations are performed).
.Pp
The format of this entry is a polynomial, as specified in the POLYNOMIALS section.
.Pp
When this entry is present in the configuration, 
.Nm
creates a preprocessor variable named 'RCC', which contains the polynomial obtained by adding each term in the id_table, and can be used in the postprocessing.
.Pp
When this entry is present in the configuration along with the -C option,
.Nm
will add a 'preprocessor_operation' entry in the configuration file to be piped to numkondo.
.Pp
Example:
To take the logarithm of the polynomial:
.D1 <%log_1<$RCC>>
.Pp
This entry is optional.
.Pp
.El
.Pp
.Sh COMMENT ON PREPROCESSOR VARIABLES, IDENTITIES AND VIRTUAL FIELDS
On the surface, preprocessor variables, identities and virtual fields can be used to perform similar tasks, but
.Nm
handles them in very different ways.
.Pp
A preprocessor variable could be replaced by an identity by introducing an extra field corresponding to the variable, and using an identity to make
.Nm
replace the extra field by its definition. Using a preprocessor variable will, however, be more convenient since no extra field needs to be introduced.
.Pp
Virtual fields could also play the role of preprocessor variables, in that they can be used to simplify the configuration file. However, virtual fields are not replaced by their corresponding expression until their average is computed, and, in the various manipulations required to carry out the computations, the monomials containing virtual fields will be manipulated and virtual fields commuted with other fields. As a consequence, virtual fields must commute with all other fields, which severely limits their potential role as a preprocessor variable.
.Pp
In short, preprocessor variables are meant to be used to simplify the configuration file, identities, to implement identities between fields, and virtual fields to reduce the memory footprint of
.Nm .
.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
.Nm
implements some elementary symbolic algebra in order to parse polynomials.
.Pp
The format of polynomials is defined recursively. If the polynomial contains no '<', then it is said to be 'terminal'. Terminal 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
If the polynomial is not terminal, then it is of the form
.D1 <polynomial>operation<polynomial>
where 'operation' is either '+' or '*', or
.D1 <%func<polynomial>>
where 'func' is 'exp' or 'log_1'. '<%exp<P>>' returns the exponential of P, whereas '<%log_1<P>>' returns log(1+P).
.Pp
.Nm
parses polynomials by recursing through this structure, adding and multiplying terminal polynomials when '+' and '*' operations are encountered, and taking exponentials and logarithms when '%exp' or '%log_1' are encountered.
.Pp
Example:
.D1 <(1)+((3/2)s{2}+(-1)s{-1}+3)[l1][l2][f100][f1001][f101]>*<%exp<[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) ,
.Pp