# Readme Ferflow.jl

This is a framework to compute flow observables based on LatticeGPU (https://igit.ific.uv.es/alramos/latticegpu.jl). 

## Input file

A template for the input file can be found at input/FerFlow.in.

* [Run]

 - user : Identifier for the person launching the run.
 - name : Identifier for the name of the run. The output files will be named acording to this field

* [Space]

 - bc : Boundary conditions. , 0 -> PERIODIC, 1 -> SF_ORBI, 2 -> SF_AFWB, 3 -> OPEN
 - size : Lattice size. The last component is the time extent.
 - blocks : Sub-lattices parallelization on the GPU. Each sub-lattice length must divide each lattice length.
 
* [HMC]

 - nth : Number of thermalization steps.
 - beta : Value of the inverse coupling.
 - c0 : Parameter defining the gauge action

   c0=1: Wilson plaquette action.
   c0=5/3: Tree-level improved Lüscher-Weisz action.
   c0=3.648: Iwasaki gauge action.

 - cG : Boundary improvement coefficient for the gauge field.
 - dmeas : Distance between measurements. 
 - eps : Step size of the hmc integration. The default integrator is omf4.
 - ns : Number of steps in each integration of the HMC.

* [Fermion]

 - kappa : Value of the hopping parameter.
 - theta : Phase for the fermion field in the spatial directions.
 - theta_t : Phase for the fermion field in the time direction.
 - csw : Sheikholeslami-Wohlert coefficient.
 - ct : Boundary improvement coefficient for the fermion field.
 - tsource : Position of the noise source.
 
* [Measurements]

 - N_noise : Number of noise sources for the fermions.
 - Flow_times : Flow times (in units of $a^2$) where correlation functions and energy density are measured. They mustt be in ascending order.
 - Nsaves : Intermediate saves donde when integrating the adjoint flow equation (backflow). Each intermediate save stores one gauge configuration in the CPU memory.
  - tolerance : Tolerance for the solver (CG solver).
 - maxiter : Maximum number or iterations of the solver

Note that some parameters may not be used in certain conditions, like most HMC parameters in the case where configurations are read as input (see below), but they are still needed as input.

## Running the code

To start the run, one simply has to execute the main.jl program with the input file:

   $ julia main.jl -i ./input/Ferflow.in
   
This will generate a file called `RUN_ON_RUNAME` in the main directory, where `RUNAME` is the name of the run in the input file. To stop the run, simply delete that file and the run will stop in the next Monte-Carlo step.

There are some more useful flags:

* -G : Selects the GPU to run the job. Default is 0.

* --cern : Read the gauge config with cern format. Without this flag, the format is assumed to be the native LGPU format.

* -c : Specifies a list of configurations to measure in. If this flag is included, the HMC is not performed.

The list must be a plain text file with the path to the corresponding configurations, one per line, with respect to the `./cnfg/` directory. For example, if the configuration files are in `./cnfg/list_of_configurations/`, the text file should look something like this

list_of_configurations/config1
list_of_configurations/config2
list_of_configurations/config3
list_of_configurations/config4
...

In this case, the run can also be stopped by deleting the `RUN_ON_RUNAME` file, or it will stop when the list is fully processed.

Another example of execution command with these flags is

   $ julia main.jl -i ./input/Ferflow.in -c 'list_of_configurations' --cern -G 1

## Output

During the run, two files will be generated and updated in the `./output/` directory, named acording to the run name in the input file. The first one is a `.log` file with readable information about the run.

The results are outputed in a `.bdio` format ( http://bdio.org ). For a Julia implementation of BDIO, see https://gitlab.ift.uam-csic.es/alberto/bdio.jl . If these files already exist when starting the run, all will be appended to them. In particular, the `read_ff` function (see below) will still work as long as the number of sources and flow times are the same, and the log will contain the information of both runs.

To read the data, one can use the function `read_ff(name::String)`, available in `./src/utils.jl` . The output is a set of Arrays with the following data:

- Eoft[Nmc,Nfl] : Array containing the value of the energy density for the Monte-Carlo chain (first index) and flow times (second index).
- pp_corr[Nmc,T,Nsrc] : pseudoscalar-pseudoscalar correlator at flow time zero. All correlation functions are averaged over 3d-noise sources at tsrc and then averaged over the volume in the sink.
- ap_corr[Nmc,T,Nsrc] : axial-pseudoscalar correlator at flow time zero.
- pp_corr_t[Nmc,T,Nsrc,Nfl] : pseudoscalar-pseudoscalar correlator at positive flow times, where the source is at zero flow time.
- ap_corr_t[Nmc,T,Nsrc,Nfl] : axial-pseudoscalar correlator at positive flow times, where the source is at zero flow time.
- pp_corr_tfl[Nmc,T,Nsrc,Nfl] : pseudoscalar-pseudoscalar correlator at positive flow times, where the source is at the final flow time.
- ap_corr_tfl[Nmc,T,Nsrc,Nfl] : axial-pseudoscalar correlator at positive flow times, where the source is at the final flow time.
- Sigma[Nmc,T,Nfl] : `cfl` independent contribution to the one point function. See arXiv: 1302.5246 for details
- Sigma_cfl[Nmc,T,Nfl] : `cfl` dependent contribution to the one point function. The final result for the quark condensate is 'Sigma' + C_fl*'Sigma_cfl'. See arXiv: 1302.5246 for details. 
- Phat_t[Nmc,Nsc,Nfl] : Correlation function between the pseudoscalar quark density and pseudoscalar density for the Lagrange multiplier field at zero flow time using random noise sources over all the volume and front flow.

The variables in brackets in the above list define the dimension of the output arrays. Monte-Carlo length index (Nmc), euclidean time (T), noise source index (Nsrc), flow time index (Nfl).

Another useful function in `src/utils.jl` is `uwff(file::String)`. To use this function one has to install ADerrors.jl (https://gitlab.ift.uam-csic.es/alberto/aderrors.jl). When calling this function, the output is stored in global variables with the names defined above, where the Monte-Carlo average is already performed. Note that the elements of the arrays will now be of the `uwreal` type. For more information on this package, see https://ific.uv.es/~alramos/software/aderrors/

