
Main program ms3

SYNTAX

ms3 -i <filename> [-noexp] [-a]


DESCRIPTION

This program reads gauge field configurations from disk and computes
a set of Wilson flow observables.


COMMAND-LINE OPTIONS

The program has only few options since most of the parameters are passed
through an input file. The options are

-i <filename>    Specifies the name of the input file. The name can be
                 a fully qualified name or be specified relative to the
                 working directory.

-noexp           Field configurations are normally read in exported
                 file format from the specified configuration directory.
                 If this option is set, the configurations are instead
                 expected in the imported file format on the local disks.

-a               This option specifies that the run is a continuation of
                 a previous run. All output data are appended to the
                 previous output files.


INPUT PARAMETERS

The lattice size and the process grid must be defined in the file global.h
(see README.global). All other parameters are read from the input file. An
example of a valid input file is ms3.in in this directory. The parameter
values specified in this file are:

[Run name]
name         Snoopy137             # Run name = configuration base name

[Directories]
log_dir      ../data/ms3/log       # Log file directory
dat_dir      ../data/ms3/dat       # Data file directory
loc_dir      /ndata/qcd1/cnfg      # Local configuration directory
cnfg_dir     /data/qcd1/cnfg       # Exported configuration directory

[Configurations]
first        1                     # No of the first configuration to consider
last         4                     # No of the last configuration
step         1                     # Configuration separation (last-first must
                                   # be an integer multiple of step)

[Boundary conditions]
type         2                     # Type of boundary condition (0: open,
                                   # 1: SF, 2: open-SF, 3: periodic)
phi          0.12 -0.56            # Boundary values of the gauge field at
                                   # time 0
phi'         0.92 0.76             # Boundary values of the gauge field at
                                   # time NPROC0*L0

[Wilson flow]
integrator   RK3                   # EULER: Euler, RK2: 2nd order Runge-Kutta
                                   # RK3: 3rd order Runge-Kutta
eps          2.0e-2                # Integration time step size
nstep        100                   # Number of integration steps
dnms         10                    # Number of integration steps between
                                   # observable measurements

Superfluous parameters may be deleted or commented out. If present they are
not read by the program and the specified values (if any) have no effect on
the run.

FILES

The program searches for exported field configurations

  <run name>n<int>

in the directory cnfg_dir, where <int> is the configuration number.
Imported configurations

  <run name>n<int>_0       (on process 0)
  <run name>n<int>_1       (on process 1)
  <run name>n<int>_2       (on process 2)
        ...                     ...

are searched in the directory loc_dir.

The program writes the results of the computations to the files

  <run name>.ms3.log   Log file
  <run name>.ms3.log~  Backup log file

  <run name>.ms3.dat   Measurement data file
  <run name>.ms3.dat~  Backup data file

  <run name>.ms3.par   Parameter data file
  <run name>.ms3.par~  Backup parameter data file

in the directories log_dir (log file) and dat_dir (data files). The parameter
file is created at the beginning of the run and remains unchanged after that.
The backup log and data files are updated each time a configuration is fully
processed.

The directories log_dir and dat_dir, as well as the directory cnfg_dir if the
-noexp option is not set, must be accessible from process 0. If the -noexp
option is set, the directory loc_dir must be accessible from all processes.


OUTPUT DATA

For each configuration, the Wilson flow is integrated from flow time 0 to time
"nstep"*"eps" in steps of eps using the specified integrator. After every
"dnms" integration steps, the time-slice sums of the densities of the Wilson
plaquette action, the Yang-Mills action and the topological charge are
computed (see uflds/plaq_sum.c, tcharge/ftensor.c, tcharge/ym_action.c and
tcharge/tcharge.c).

At the beginning of the measurement data file the program writes the data
contained in the header structure

static struct
{
   int dn,nn,tmax;
   double eps;
} file_head;

where dn="dnms", nn="nstep"/"dnms" and tmax=NPROC0*L0. After the header data,
the data file contains a sequence of data structures

static struct
{
   int nc;
   double **Wsl,**Ysl,**Qsl;
} data;

labeled by the configuration number nc. In each case the time-slice sums of
the densities of the Wilson plaquette action, the Yang-Mills action and the
topological charge are written to the arrays

  Wsl[in][t]   (in=0,..,nn, t=0,..,tmax-1)
  Ysl[in][t]
  Qsl[in][t]

See the functions write_file_head() and write_data() in the program file
ms3.c for the exact order in which the data are written to the output files.


BINARY FILE FORMAT

The log files are ASCII files that should be readable on any machine. The
data files, on the other hand, are written in binary format using the fwrite()
function. Integers are written as 4 byte signed integers and floating-point
numbers according to the IEEE-754 standard for double-precision numbers.

Binary data written to disk are converted to little endian byte order if the
machine is big endian. Field configurations and measurement data stored on
disk are thus always in little endian byte order independently of the machine
that is used.


SAFETY MEASURES AND ERROR REPORTING

A number of safety measures have been implemented:

- It is not possible to overwrite an existing log or data file; these
  must first be deleted or renamed by hand if a run is to be repeated.

- Appending a run to a previous measurement run is only possible if the run
  name and all relevant parameters match. Moreover, the new configuration
  sequence must extend the previous one with the same configuration spacing.

- The accessibility of the various directories and the compatibility
  of the chosen parameters is checked at the beginning of the program.

Any attempt to force illegal operations leads to an abnormal termination of
the program, with an informative message being written either to the log file
or the file STARTUP_ERROR in the program directory (if the error occurs before
the log file is opened).

It should be noted that filenames may not be longer than 127 characters. The
program checks at an early stage whether this is the case or not. Longer
filenames can be accommodated by setting the macro NAME_SIZE in the header
file global.h to a larger value.


CHECKPOINTS AND EARLY TERMINATION

The program can be stopped gracefully by touching a file in the log directory
with the same name as the log file but with extension .end instead of .log. It
may take a while until the program exits, because it will only do so when the
current field configuration is fully processed.

If the machine crashes, or if the program was stopped in the way described,
the run can always be continued starting from the saved output files. However,
after a crash, the log and data files may be corrupted, in which case they
must first be restored from the backup files.
