

********************************************************************************

                       Flags and parameter data base

********************************************************************************

The modules in this directory serve to control the program flow and help
to ensure that the different programs do not interfere with each other
in unintended ways.


Files
-----

action_parms.c   Action parameter data base

dfl_parms.c      Deflation parameters

flags.c          Flags data base input and query programs (see README.flags)

force_parms.c    Force parameter data base

hmc_parms.c      Basic HMC parameters

lat_parms.c      Lattice parameters

mdint_parms.c    Molecular-dynamics integrator data base

rat_parms.c      Rational function parameter data base

rw_parms.c       Reweighting factor parameter data base

sap_parms.c      SAP parameters

sf_parms.c       Schroedinger functional boundary values

solver_parms.c   Solver parameter data base


Include file
------------

The file flags.h defines the prototypes for all externally accessible
functions that are defined in the *.c files listed above


List of functions
-----------------

action_parms_t set_action_parms(int iact,action_t action,int ipf,
                                int im0,int *irat,int *imu,int *isp)
  Sets the parameters in the action parameter set number iact and returns
  a structure containing them (see the notes).

action_parms_t action_parms(int iact)
  Returns a structure containing the action parameter set number iact
  (see the notes).

void read_action_parms(int iact)
  On process 0, this program scans stdin for a line starting with the
  string "[Action <int>]" (after any number of blanks), where <int> is
  the integer value passed by the argument. An error occurs if no such
  line or more than one is found. The lines

    action   <action_t>
    ipf      <int>
    im0      <int>
    irat     <int> <int> <int>
    imu      <int> [<int>]
    isp      <int> [<int>]

  are then read using read_line() [utils/mutils.c]. Depending on the
  value of "action", some lines are not read and can be omitted in
  the input file. The number of integer items on the lines with tag
  "imu" and "isp" depends on the action too. The data are then added
  to the data base by calling set_action_parms(iact,...).

void print_action_parms(void)
  Prints the parameters of the defined actions to stdout on MPI
  process 0.

void write_action_parms(FILE *fdat)
  Writes the parameters of the defined actions to the file fdat on
  MPI process 0.

void check_action_parms(FILE *fdat)
  Compares the parameters of the defined actions with those stored
  on the file fdat on MPI process 0, assuming the latter were written
  to the file by the program write_action_parms().

dfl_parms_t set_dfl_parms(int *bs,int Ns)
  Sets the parameters of the deflation subspace. The parameters are

    bs[4]          Sizes of the blocks in DFL_BLOCKS block grid.

    Ns             Number of deflation modes per block (must be
                   even and non-zero).

  The return value is a structure that contains the above parameters.
  Note that these parameters can only be set once.

dfl_parms_t dfl_parms(void)
  Returns the parameters currently set for the deflation subspace.

dfl_pro_parms_t set_dfl_pro_parms(int nkv,int nmx,double res)
  Sets the parameters used when applying the deflation projection in the
  deflated solver program dfl_sap_gcr(). The parameters are

    nkv            Maximal number of Krylov vectors to be used by the
                   solver for the little Dirac equation before a restart.

    nmx            Maximal total number of Krylov vectors generated by
                   the solver for the little Dirac equation.

    res            Required relative residue when solving the little
                   Dirac equation.

  The return value is a structure that contains the above parameters.

dfl_pro_parms_t dfl_pro_parms(void)
  Returns the parameters currently set for the deflation projectors in
  the deflated solver program dfl_sap_gcr().

dfl_gen_parms_t set_dfl_gen_parms(double kappa,double mu,
                                  int ninv,int nmr,int ncy,
                                  int nkv,int nmx,double res)
  Sets the parameters of the inverse iteration procedure that generates
  the deflation subspace. The parameters are

    kappa          Hopping parameter of the Dirac operator.

    mu             Twisted mass parameter.

    ninv           Total number of inverse iteration steps (ninv>=4).

    nmr            Number of block minimal residual iterations to be
                   used when the SAP smoother is applied.

    ncy            Number of SAP cycles per inverse iteration.

  The return value is a structure that contains the above parameters and
  the bare mass m0 that corresponds to the hopping parameter kappa.

dfl_gen_parms_t dfl_gen_parms(void)
  Returns the parameters currently set for the generation of the deflation
  subspace plus the corresponding bare mass m0.

dfl_upd_parms_t set_dfl_upd_parms(double dtau,int nsm)
  Sets the parameters of the deflation subspace update scheme. The
  parameters are

    dtau           Molecular-dynamics time separation between
                   updates of the deflation subspace.

    nsm            Number of deflated smoothing interations to be
                   applied when the subspace is updated.

  The return value is a structure that contains the above parameters.

dfl_upd_parms_t dfl_upd_parms(void)
  Returns the parameters currently set for the deflation subspace
  update scheme.

void print_dfl_parms(int ipr)
  Prints the parameters of the deflation subspace, the projectors, the
  subspace generation algorithm and the update scheme to stdout on MPI
  process 0. The update scheme is omitted if ipr=0.

void write_dfl_parms(FILE *fdat)
  Writes the parameters of the deflation subspace, the projectors, the
  subspace generation algorithm and the update scheme to the file fdat
  on MPI process 0.

void check_dfl_parms(FILE *fdat)
  Compares the parameters of the deflation subspace, the projectors the
  subspace generation algorithm and the update scheme with the values
  stored on the file fdat on MPI process 0, assuming the latter were
  written to the file by the program write_dfl_parms() (mismatches of
  maximal solver iteration numbers are not considered to be an error).

void set_flags(event_t event)
  Reports an event to the data base, which changed the global gauge
  gauge or SW fields.

void set_grid_flags(blk_grid_t grid,event_t event)
  Reports an event to the data base, which changed the gauge or SW
  fields on the specified block grid.

int query_flags(query_t query)
  Queries the data base on the status of the global gauge or SW
  fields. The program returns 1 or 0 depending on whether the answer
  to the specified query is "yes" or "no". If the query is unknown to
  the data base, the program returns -1.

int query_grid_flags(blk_grid_t grid,query_t query)
  Queries the data base on the status of the gauge or SW fields on
  the specified block grid. The program returns 1 or 0 depending on
  whether the answer to the specified query is "yes" or "no". If the
  query is unknown to the data base, the program returns -1.

void print_flags(void)
  Prints the current values of all flags related to the global gauge
  and SW fields to stdout from process 0.

void print_grid_flags(blk_grid_t grid)
  Prints the current values of all flags related to the gauge and SW
  fields on the specified block grid to stdout from process 0.

force_parms_t set_force_parms(int ifr,force_t force,int ipf,int im0,
                              int *irat,int *imu,int *isp,int *ncr)
  Sets the parameters in the force parameter set number ifr and returns
  a structure containing them (see the notes).

force_parms_t force_parms(int ifr)
  Returns a structure containing the force parameter set number ifr
  (see the notes).

void read_force_parms(int ifr)
  On process 0, this program scans stdin for a line starting with the
  string "[Force <int>]" (after any number of blanks), where <int> is
  the integer value passed by the argument. An error occurs if no such
  line or more than one is found. The lines

    force   <force_t>
    ipf     <int>
    im0     <int>
    irat    <int> <int> <int>
    imu     <int> [<int>]
    isp     <int> [<int>]
    ncr     <int> [<int>]

  are then read using read_line() [utils/mutils.c]. Depending on the
  value of "force", some lines are not read and can be omitted in the
  input file. The number of integer items on the lines with tag "imu"
  and "isp" and "ncr" depends on the force too. The data are then added
  to the data base by calling set_force_parms(ifr,...).

void read_force_parms2(int ifr)
  Same as read_force_parms() except that only the lines

    force   <force_t>
    isp     <int> [<int>]
    ncr     <int> [<int>]

  are read from stdin. All other force parameters are inferred from
  the parameters of the action no ifr so that the force is the one
  deriving from that action. An error occurs if the parameters of the
  action no ifr have not previously been added to the data base or
  if the force and action types do not match.

void print_force_parms(void)
  Prints the parameters of the defined forces to stdout on MPI
  process 0.

void print_force_parms2(void)
  Prints the parameters of the defined forces to stdout on MPI
  process 0 in a short format corresponding to read_force_parms2().

void write_force_parms(FILE *fdat)
  Writes the parameters of the defined forces to the file fdat on
  MPI process 0.

void check_force_parms(FILE *fdat)
  Compares the parameters of the defined forces with those stored
  on the file fdat on MPI process 0, assuming the latter were written
  to the file by the program write_force_parms().

hmc_parms_t set_hmc_parms(int nact,int *iact,int npf,int nmu,
                          double *mu,int nlv,double tau)
  Sets some basic parameters of the HMC algorithm. The parameters are

    nact        Number of terms in the total action

    iact        Indices iact[i] of the action terms (i=0,..,nact-1)

    npf         Number of pseudo-fermion fields on which the action
                depends

    nmu         Number of twisted mass parameters on which the
                pseudo-fermion actions and forces depend

    mu          Twisted masses mu[i] (i=0,..,nmu-1)

    nlv         Number of levels of the molecular-dynamics integrator

    tau         Molecular-dynamics trajectory length

  The total action must include the gauge action, but pseudo-fermion
  actions are optional and the momentum action is treated separately.
  The program returns a structure that contains the parameters listed
  above.

hmc_parms_t hmc_parms(void)
  Returns a structure containing the current values of the parameters
  listed above.

void print_hmc_parms(void)
  Prints the lattice parameters to stdout on MPI process 0.

lat_parms_t set_lat_parms(double beta,double c0,
                          double kappa_u,double kappa_s,double kappa_c,
                          double csw,double cG,double cF)
  Sets the basic lattice parameters. The parameters are

    beta           Inverse bare coupling (beta=6/g_0^2).

    c0             Coefficient of the plaquette loops in the gauge
                   action (see doc/gauge_action.pdf).

    kappa_{u,s,c}  Hopping parameters of the u, s and c sea quarks. The
                   u and the d quark have the same hopping parameter and
                   quarks with vanishing hopping parameter are ignored.

    csw            Coefficient of the Sheikholeslami-Wohlert term.

    cG,cF          Coefficients of the gauge and fermion O(a) boundary
                   counterterms.

  The return value is a structure that contains the lattice parameters
  and the associated bare quark masses m0u, m0s and m0c.

lat_parms_t lat_parms(void)
  Returns the current lattice parameters in a structure that contains
  the above parameters plus the bare quark masses.

void print_lat_parms(void)
  Prints the lattice parameters to stdout on MPI process 0.

bc_parms_t set_bc_parms(int type,
                        double cG,double cG_prime,
                        double cF,double cF_prime,
                        double *phi,double *phi_prime)
  Sets the boundary conditions and the associated parameters of the
  action. The parameters are

    type           Chosen type of boundary condition (0: open, 1: SF,
                   2: open-SF, 3: periodic).

    cG,cG_prime    Gauge action improvement coefficients at time 0
                   and T, respectively.

    cF,cF_prime    Fermion action improvement coefficients at time 0
                   and T, respectively.

    phi[0],        First two angles that define the boundary values of
    phi[1]         the gauge field at time 0.

    phi_prime[0],  First two angles that define the boundary values of
    phi_prime[1]   the gauge field at time T.

  The return value is a structure that contains these parameters plus
  the third angles. In this structure, the improvement coefficients and
  the angles are stored in the form of arrays cG[2],cF[2] and phi[2][3],
  where cG[0],cF[0],phi[0][3] and cG[1],cF[1],phi[1][3] are the para-
  meters at time 0 and T, respectively
   Parameters that are not required for the specification of the chosen
  boundary conditions are not read and are set to their default values
  in the data base (angles to 0, improvement coefficients to 1). In the
  case of SF boundary conditions (type 1), the program only reads cG,cF
  and the angles phi,phi_prime and then sets cG_prime=cG,cF_prime=cF.
  When open-SF boundary conditions are chosen, all parameters except for
  the angles phi are read.

bc_parms_t bc_parms(void)
  Returns a structure that contains the boundary parameters.

void print_bc_parms(void)
  Prints the boundary parameters to stdout on MPI process 0.

void write_bc_parms(FILE *fdat)
  Writes the boundary parameters to the file fdat on MPI process 0.

void check_bc_parms(FILE *fdat)
  Compares the currently set boundary parameters with the values stored
  on the file fdat on MPI process 0, assuming the latter were written to
  the file by the program write_bc_parms().

double sea_quark_mass(int im0)
  Returns the bare sea quark mass m0u if im0=0, m0s if im0=1 and m0c
  if im0=2. In all other cases DBL_MAX is returned.

sw_parms_t set_sw_parms(double m0)
  Sets the parameters of the SW term. The parameter is

    m0            Bare quark mass.

  The return value is a structure that contains the mass m0 and the
  improvement coefficients csw and cF, the latter being copied from
  the list of the lattice parameters.

sw_parms_t sw_parms(void)
  Returns the parameters currently set for the SW term. The values
  of the coefficients csw and cF are copied from the lattice parameter
  list.

tm_parms_t set_tm_parms(int io)
  Sets the twisted-mass flag. The parameter is

    io            Twisted-mass flag. If io=1, the twisted-mass term
                  in the Dirac operator, the SAP preconditioner and
                  the little Dirac operator is turned off on the odd
                  lattice sites. Otherwise it is applied everywhere.

  The return value is structure that contains the twisted-mass flag.

tm_parms_t tm_parms(void)
  Returns a structure containing the twisted-mass flag.

mdint_parms_t set_mdint_parms(int ilv,integrator_t integrator,double lambda,
                              int nstep,int nfr,int *ifr)
  Sets the parameters of the molecular-dynamics integrator at level
  ilv and returns a structure containing them (see the notes).

mdint_parms_t mdint_parms(int ilv)
  Returns a structure containing the parameters of the integrator at
  level ilv (see the notes).

void read_mdint_parms(int ilv)
  On process 0, this program scans stdin for a line starting with the
  string "[Level <int>]" (after any number of blanks), where <int> is
  the integer value passed by the argument. An error occurs if no such
  line or more than one is found. The lines

    integrator   <integrator_t>
    lambda       <double>
    nstep        <int>
    forces       <int> [<int>]

  are then read using read_line() [utils/mutils.c]. The line tagged
  "lambda" is required only when the specified integrator is the 2nd
  order OMF integrator. The line tagged "forces" must contain the
  indices of the forces (separated by white space) that are to be
  integrated at this level. On exit, the data are entered in the data
  base by calling set_mdint_parms(ilv,...).

void print_mdint_parms(void)
  Prints the parameters of the defined integrator levels to stdout
  on MPI process 0.

void write_mdint_parms(FILE *fdat)
  Writes the parameters of the defined integrator levels to the file
  fdat on MPI process 0.

void check_mdint_parms(FILE *fdat)
  Compares the parameters of the defined integrator levels with those
  stored on the file fdat on MPI process 0, assuming the latter were
  written to the file by the program write_mdint_parms().

rat_parms_t set_rat_parms(int irp,int degree,double *range)
  Sets the parameters in the rational function parameter set number
  irp and returns a structure containing them (see the notes).

rat_parms_t rat_parms(int irp)
  Returns a structure containing the rational function parameter set
  number irp (see the notes).

void read_rat_parms(int irp)
  On process 0, this program scans stdin for a line starting with the
  string "[Rational <int>]" (after any number of blanks), where <int> is
  the integer value passed by the argument. An error occurs if no such
  line or more than one is found. The lines

    degree  <int>
    range   <double> <double>

  are then read using read_line() [utils/mutils.c] and the data are
  entered into the data base by calling set_rat_parms().

void print_rat_parms(void)
  Prints the defined rational function parameter sets to stdout on MPI
  process 0.

void write_rat_parms(FILE *fdat)
  Writes the defined rational function parameter sets to the file fdat
  on MPI process 0.

void check_rat_parms(FILE *fdat)
  Compares the defined rational function parameter sets with those
  on the file fdat on MPI process 0, assuming the latter were written
  to the file by the program write_rat_parms().

rw_parms_t set_rw_parms(int irw,rwfact_t rwfact,int im0,int nsrc,
                        int irp,int nfct,double *mu,int *np,int *isp)
  Sets the parameters in the reweighting factor parameter set number
  irw and returns a structure containing them (see the notes).

rw_parms_t rw_parms(int irw)
  Returns a structure containing the reweighting factor parameter set
  number irw (see the notes).

void read_rw_parms(int irw)
  On process 0, this program scans stdin for a line starting with the
  string "[Reweighting factor <int>]" (after any number of blanks), where
  <int> is the integer value passed through the argument. An error occurs
  if no such line or more than one is found. The lines

    rwfact   <rwfact_t>
    im0      <int>
    nsrc     <int>
    irp      <int>
    mu       <double> [<double>]
    np       <int> [<int>]
    isp      <int> [<int>]

  are then read using read_line() [utils/mutils.c] and the data are
  added to the data base by calling set_rw_parms(irw,...). Depending
  on the value of "rwfact", some lines are not read and can be omitted
  in the input file. The number of items on the lines with tag "mu",
  "np" and "isp" depends on the reweighting factor too (see the notes).

void print_rw_parms(void)
  Prints the defined reweighting factor parameter sets to stdout on
  MPI process 0.

void write_rw_parms(FILE *fdat)
  Writes the defined reweighting factor parameter sets to the file fdat
  on MPI process 0.

void check_rw_parms(FILE *fdat)
  Compares the defined reweighting factor parameter sets with those
  on the file fdat on MPI process 0, assuming the latter were written
  to the file by the program write_rw_parms().

sap_parms_t set_sap_parms(int *bs,int isolv,int nmr,int ncy)
  Sets the parameters of the SAP preconditioner. The parameters are

    bs[4]         Sizes of the blocks in SAP_BLOCKS block grid.

    isolv         Block solver to be used (0: plain MinRes,
                  1: eo-preconditioned MinRes).

    nmr           Number of block solver iterations.

    ncy           Number of SAP cycles to be applied.

  The return value is a structure that contains the parameters of the
  SAP preconditioners. The block sizes bs[4] can only be set once, but
  the values of the other parameters may be changed by calling the
  program again.

sap_parms_t sap_parms(void)
  Returns the parameters currently set for the SAP preconditioner.

void print_sap_parms(int ipr)
  Prints the SAP parameters to stdout on MPI process 0. Depending
  on whether ipr!=0 or 0, the full information is printed or only
  the block size.

sf_parms_t set_sf_parms(double *phi,double *phi_prime)
  Sets the parameters of the boundary fields in the Schroedinger
  functional. The parameters are

    phi           Angles phi[0],phi[1] at time 0.

    phi_prime     Angles phi[0],phi[1] at time T.

  See the notes for further explanations. This program may only be
  called once.

sf_parms_t sf_parms(void)
  Returns the parameters of the boundary fields currently set.

void print_sf_parms(void)
  Prints the parameters of the boundary fields to stdout on MPI
  process 0.

void write_sf_parms(FILE *fdat)
  Writes the parameters of the boundary fields to the file fdat on
  MPI process 0.

void check_sf_parms(FILE *fdat)
  Compares the parameters of the boundary fields with the values
  stored on the file fdat on MPI process 0, assuming the latter were
  written to the file by the program write_sf_parms().

int sf_flg(void)
  Returns 1 if the Schroedinger-functional boundary values have been
  initialized and 0 otherwise.

solver_parms_t set_solver_parms(int isp,solver_t solver,
                                int nkv,int isolv,int nmr,int ncy,
                                int nmx,double res)
  Sets the parameters in the solver parameter set number isp and returns
  a structure containing them (see the notes).

solver_parms_t solver_parms(int isp)
  Returns a structure containing the solver parameter set number
  isp (see the notes).

void read_solver_parms(int isp)
  On process 0, this program scans stdin for a line starting with the
  string "[Solver <int>]" (after any number of blanks), where <int> is
  the integer value passed by the argument. An error occurs if no such
  line or more than one is found. The lines

    solver  <solver_t>
    nkv     <int>
    isolv   <int>
    nmr     <int>
    ncy     <int>
    nmx     <int>
    res     <double>

  are then read one by one using read_line() [utils/mutils.c]. The
  lines with tags nkv,..,ncy may be absent in the case of the CGNE
  and MSCG solvers (see the notes). The data are then added to the
  data base by calling set_solver_parms(isp,...).

void print_solver_parms(int *isap,int *idfl)
  Prints the parameters of the defined solvers to stdout on MPI
  process 0. On exit the flag isap is 1 or 0 depending on whether
  one of the solvers makes use of the Schwarz Alternating Procedure
  (SAP) or not. Similarly, the flag idfl is set 1 or 0 depending on
  whether deflation is used or not. On MPI processes other than 0,
  the program does nothing and sets isap and idfl to zero.

void write_solver_parms(FILE *fdat)
  Writes the parameters of the defined solvers to the file fdat on
  MPI process 0.

void check_solver_parms(FILE *fdat)
  Compares the parameters of the defined solvers with those stored
  on the file fdat on MPI process 0, assuming the latter were written
  to the file by the program write_solver_parms(). Mismatches of the
  maximal solver iteration number are not considered to be an error.
